Spryker documentation center. https://docs.spryker.com/ Fri, 26 Jun 2026 02:36:25 +0000 Jekyll v4.2.2 This document describes the changes that have been recently released. For additional support with this content, contact our support. If you found a new security vulnerability, contact us at **security@spryker.com**. --- ## Release notes for spryker-php 20260626 **Improvements**: - Fixed the `Manifest` and `View Diff` links - Fixed the Slack message duplication Fri, 26 Jun 2026 02:35:51 +0000 https://docs.spryker.com/docs/about/all/releases/image-releases/spryker-php/release-notes-spryker-php-20260626.html https://docs.spryker.com/docs/about/all/releases/image-releases/spryker-php/release-notes-spryker-php-20260626.html <p>This page continues the <a href="/docs/integrations/spryker-glue-api/getting-started-with-apis/api-strategy.html">Spryker API Strategy</a>. It covers the API types on the roadmap, how to choose one, why API Platform integration, your migration decision, and the rollout timeline.</p> <h2 id="whats-on-the-roadmap">What’s on the roadmap</h2> <p>Planned API types, listed so you can plan ahead. Availability is announced per type; treat these as direction, not a build target.</p> <table> <thead> <tr> <th>API type</th> <th>Application</th> <th>Caller (actor)</th> <th>Use it when</th> </tr> </thead> <tbody> <tr> <td><strong>Merchant API</strong></td> <td>Backend</td> <td>Marketplace merchant (single-merchant scope)</td> <td>A merchant manages their own catalog, offers, orders, or payouts record-by-record through a UI or tool</td> </tr> <tr> <td><strong>Merchant Data Exchange API</strong></td> <td>Backend</td> <td>Merchant-side integration system</td> <td>A merchant bulk-imports or bulk-exports their own data between their systems and the marketplace</td> </tr> <tr> <td><strong>Data Exchange API</strong></td> <td>Backend</td> <td>Platform-operator integration system</td> <td>The operator moves large datasets in or out at platform level (PIM, ERP, OMS, BI)</td> </tr> <tr> <td><strong>Async Event API</strong></td> <td>Backend</td> <td>Event subscriber (broker or webhook)</td> <td>An external system needs to react to Spryker events instead of polling</td> </tr> </tbody> </table> <hr /> <h2 id="choosing-an-api-type">Choosing an API type</h2> <p>Pick by <strong>who is calling</strong> and <strong>the shape of the data flow</strong> (one record at a time, bulk, or event-driven).</p> <table> <thead> <tr> <th>Your situation</th> <th>Use</th> </tr> </thead> <tbody> <tr> <td>A customer browses, shops, and checks out</td> <td>Storefront API</td> </tr> <tr> <td>An administrator manages catalog, orders, or customers</td> <td>Back Office API</td> </tr> <tr> <td>A merchant manages their own data through a UI, record by record</td> <td>Merchant API</td> </tr> <tr> <td>A merchant bulk-imports or bulk-exports their own data</td> <td>Merchant Data Exchange API</td> </tr> <tr> <td>The platform operator moves large datasets (PIM, ERP, OMS)</td> <td>Data Exchange API</td> </tr> <tr> <td>An external system reacts to events (order placed, stock changed)</td> <td>Async Event API</td> </tr> </tbody> </table> <p><strong>Each API type has its own actor and authentication</strong>, so a token for one type does not grant access to another. Storefront uses customer authentication; Back Office uses administrator authentication; Merchant uses merchant-scoped authentication that restricts every call to a single merchant’s data; the data and event types use system credentials issued by the platform operator.</p> <hr /> <h2 id="why-api-platform-integration">Why API Platform integration</h2> <p>What you get, in developer terms:</p> <ul> <li><strong>Contract-first APIs</strong> → the contract is the source of truth, so you can generate typed clients and catch breaking changes before they ship.</li> <li><strong>Versioning and content negotiation</strong> → platform upgrades stop silently breaking your integration; you opt into changes.</li> <li><strong><code>application/csv</code>, <code>application/xml</code>, <code>application/ld+json</code></strong> → your ERP or PIM integration can drop its custom transformation layer and exchange the format it already speaks.</li> <li><strong>Built for large data exchange</strong> → bulk import/export is a first-class path, not a workaround.</li> <li><strong>Standardized integration patterns</strong> → the same conventions across every API type, so a second integration is faster than the first.</li> <li><strong>Runs alongside Glue</strong> → adopt it per endpoint, with no flag day and nothing to switch off.</li> </ul> <hr /> <h2 id="before-and-after-your-migration-decision">Before and after: your migration decision</h2> <p>You only have a decision to make if you’re on Glue and weighing a move. Here’s the whole picture:</p> <table> <thead> <tr> <th></th> <th>On Glue today</th> <th>After moving to API Platform integration</th> </tr> </thead> <tbody> <tr> <td>Existing endpoints</td> <td>Keep working, supported, no EOL</td> <td>Unchanged — migrate only what you choose</td> </tr> <tr> <td>New endpoints you build</td> <td>Possible, but no new Spryker features land here</td> <td>Recommended path; new features available</td> </tr> <tr> <td>Breaking changes on upgrade</td> <td>Possible</td> <td>Controlled through versioning</td> </tr> <tr> <td>Data format handling</td> <td>Custom transformation in your code</td> <td>Native CSV / XML / JSON-LD</td> </tr> <tr> <td>Effort to adopt</td> <td>—</td> <td>Incremental, endpoint by endpoint</td> </tr> </tbody> </table> <p><strong>You should consider moving when</strong> you’re building a new integration, exchanging large datasets, connecting an external system (ERP, PIM, OMS), or you want upgrade-safe versioning. <strong>You can stay on Glue</strong> indefinitely for everything that already works.</p> <p>Spryker supports the move with documentation of behavioral differences, endpoint-by-endpoint migration, and conversion tools and reference implementations.</p> <hr /> <h2 id="timeline">Timeline</h2> <p>API Platform integration is generally available. The rollout ran as follows:</p> <table> <thead> <tr> <th>Milestone</th> <th>When</th> <th>What it means</th> </tr> </thead> <tbody> <tr> <td>Early access</td> <td>Through Q1 2026</td> <td>Available for new features ahead of GA, with a limited support scope; native features (authentication, codebuckets, full JSON:API) not yet fully integrated</td> </tr> <tr> <td>Glue feature freeze</td> <td>From Q1 2026</td> <td>New Spryker features target API Platform integration only. Glue gets bugfixes, security, and compatibility — no new endpoints</td> </tr> <tr> <td>General availability</td> <td>Apr 30, 2026</td> <td>Full support; recommended for all new integrations</td> </tr> <tr> <td>Glue REST module migration</td> <td>In progress</td> <td>Spryker-provided modules move to API Platform. Check the <a href="/docs/dg/dev/architecture/api-platform/migrate-to-api-platform-status.html">migration status page</a></td> </tr> </tbody> </table> <p>The Q1 feature freeze and the April GA work together: from Q1, new features were built on API Platform integration and shipped through the <strong>early-access</strong> window, reaching full support at GA. Feature freeze means no new Glue functionality — it is not deprecation, and there is no End-of-Life.</p> <hr /> <h2 id="faq">FAQ</h2> <p>These cover the edge cases the tables above don’t.</p> <p><strong>How is the Merchant API different from the Back Office API?</strong> Back Office serves Spryker administrators with platform-wide scope. Merchant serves a single marketplace merchant — every call is restricted to that merchant’s own data.</p> <p><strong>How is the Merchant API different from the Merchant Data Exchange API?</strong> Both are merchant-scoped. Merchant API is for record-by-record operations through interfaces and tools. Merchant Data Exchange API is for bulk, file-based, or queue-based flows between a merchant’s systems and the marketplace.</p> <p><strong>How is the Data Exchange API different from the Merchant Data Exchange API?</strong> Same capabilities, different scope. Data Exchange operates at platform level with operator credentials. Merchant Data Exchange is restricted to one merchant’s data with per-merchant credentials.</p> <p><strong>How is the Data Exchange API different from the Async Event API?</strong> Data Exchange is request-driven — your system calls Spryker to import, export, or read. Async Event is event-driven — Spryker notifies your system when something happens. Choose by whether you poll or react.</p> Thu, 25 Jun 2026 13:34:37 +0000 https://docs.spryker.com/docs/integrations/spryker-glue-api/getting-started-with-apis/api-roadmap-and-adoption.html https://docs.spryker.com/docs/integrations/spryker-glue-api/getting-started-with-apis/api-roadmap-and-adoption.html <h2 id="what-this-means-for-you">What this means for you</h2> <ul> <li><strong>On Glue today?</strong> Nothing breaks. Glue is fully supported, there is no End-of-Life, and you don’t have to migrate existing features.</li> <li><strong>Building something new?</strong> Build it on <strong>API Platform integration</strong>. It is generally available and is where all new Spryker features ship.</li> <li><strong>Need a Spryker Core feature released after Q1 2026?</strong> It will be available through API Platform integration only.</li> </ul> <p>Everything below is supporting detail.</p> <section class='info-block info-block--warning'><i class='info-block__icon icon-warning'></i><div class='info-block__content'> <p>Glue keeps working and isn’t going away. New features are built on API Platform integration. Migration is optional.</p> </div></section> <hr /> <h2 id="how-the-pieces-fit">How the pieces fit</h2> <p>Spryker’s APIs are described by three <strong>independent</strong> axes. They are easy to confuse because some names repeat across axes, so read them as orthogonal:</p> <ol> <li><strong>Application</strong> — <em>where</em> the API lives. Two of them: <strong>Storefront API</strong> and <strong>Backend API</strong>.</li> <li><strong>API type</strong> — <em>what</em> you call and <em>who</em> the caller is (a customer, an administrator, a merchant, a system). Several types live under each application.</li> <li><strong>Foundation</strong> — <em>how</em> it’s built underneath: <strong>Glue</strong> or <strong>API Platform integration</strong>. This is a foundation beneath the API, not something you call directly.</li> </ol> <table> <thead> <tr> <th>API type</th> <th>Application (where)</th> <th>Foundation (how it’s built)</th> </tr> </thead> <tbody> <tr> <td>Storefront API</td> <td>Storefront API</td> <td>Glue <strong>or</strong> API Platform integration</td> </tr> <tr> <td>Back Office API</td> <td>Backend API</td> <td>Glue <strong>or</strong> API Platform integration</td> </tr> <tr> <td>Merchant API</td> <td>Backend API</td> <td>API Platform integration</td> </tr> <tr> <td>Merchant Data Exchange API</td> <td>Backend API</td> <td>API Platform integration</td> </tr> <tr> <td>Data Exchange API</td> <td>Backend API</td> <td>API Platform integration</td> </tr> <tr> <td>Async Event API</td> <td>Backend API</td> <td>API Platform integration</td> </tr> </tbody> </table> <p>Read the table across, not down: each API type belongs to one application and is built on one foundation, and those two facts are independent of each other. “Storefront API” names both an application and the type it hosts; “API Platform integration” is a foundation, not an endpoint you target. During the transition, an existing type can be served by either foundation.</p> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Naming watch-out</div> <p>The <strong>Backend API</strong> <em>application</em> is not the same as the <strong>Back Office API</strong> <em>type</em>. The Backend API application hosts several types of API, one of which is Back Office API.</p> </div></section> <hr /> <h2 id="what-you-can-build-on-today">What you can build on today</h2> <p>These are callable now:</p> <table> <thead> <tr> <th>API type</th> <th>Application</th> <th>Caller (actor)</th> <th>Use it when</th> </tr> </thead> <tbody> <tr> <td><strong>Storefront API</strong></td> <td>Storefront</td> <td>Customer (authenticated or guest)</td> <td>You’re building any customer-facing shopping experience</td> </tr> <tr> <td><strong>Back Office API</strong></td> <td>Backend</td> <td>Back Office administrator or trusted internal service</td> <td>You’re automating or replacing Back Office administration</td> </tr> </tbody> </table> <p>For the API types on the roadmap, guidance on choosing between them, why API Platform integration, your migration decision, and the rollout timeline, see <a href="/docs/integrations/spryker-glue-api/getting-started-with-apis/api-roadmap-and-adoption.html">Spryker API roadmap and adoption</a>.</p> <hr /> <h2 id="faq">FAQ</h2> <p>These cover the edge cases the tables above don’t.</p> <p><strong>Is API Platform integration something I call, or something underneath what I call?</strong> Underneath. You call an API type (Storefront, Back Office, and so on). API Platform integration is the foundation it’s built on, replacing Glue for new work.</p> <p><strong>How is the Backend API application different from the Back Office API type?</strong> The Backend API is the application that hosts several types. Back Office is one of those types, for administrator-level operations. Same word root, different axis.</p> <p><strong>Do I have to migrate my existing Glue APIs?</strong> No. Migration is optional and there is no End-of-Life.</p> Thu, 25 Jun 2026 11:07:26 +0000 https://docs.spryker.com/docs/integrations/spryker-glue-api/getting-started-with-apis/api-strategy.html https://docs.spryker.com/docs/integrations/spryker-glue-api/getting-started-with-apis/api-strategy.html <div class="content_box"> Spryker's API is a dedicated application layer within the Spryker Cloud Commerce OS. It's designed to provide API endpoints, process requests, and communicate with other parts of the system to manage data. Think of it as the primary interface for any external system, custom frontend, or digital touchpoint that needs to interact with your Spryker-powered commerce platform. Its main purpose is to enable headless commerce strategies, allowing you to build unique customer experiences and integrate seamlessly with a multitude of channels. Spryker's API framework offers the following types of API applications, each tailored for different use cases. </div> <div class="grid_container"> <div class="cst_cards_2"> <div class="cst_card"> <div class="cst_card_title">Storefront API</div> <div class="cst_card_desc">Storefront API is designed for consumers and customer-facing integrations. It's the API layer that powers web shops, mobile apps, marketplaces, and other client-facing systems. It is based on REST API and follows JSON:API conventions. Learn about customer-facing API endpoints for building headless commerce experiences, mobile apps, and custom storefronts.</div> <a class="cst_card_button" href="/docs/integrations/spryker-glue-api/storefront-api/storefront-api.html">Learn more</a> </div> <br> <div class="cst_card"> <div class="cst_card_title">Backend API</div> <div class="cst_card_desc">Backend API is designed for admins and system-to-system communication. Tailored for backend processes, administrative tools, or integrations with enterprise systems, such as ERP or CRM. Technically it is multi-format, but REST API is shipped out-of-the-box. A key advantage is its direct access to Spryker's business logic layer (Facades). Discover administrative API endpoints for system integration, ERP connections, and backend operations with direct facade access.</div> <a class="cst_card_button" href="/docs/integrations/spryker-glue-api/backend-api/backend-api.html">Learn more</a> </div> <br> <div class="cst_card"> <div class="cst_card_title">Spryker API Strategy for 2026</div> <div class="cst_card_desc">Spryker is evolving its API strategy by introducing <b>API Platform–based integration</b> as a <b>new, strategic integration layer</b>, while continuing to <b>fully support existing Glue APIs</b>.</div> <a class="cst_card_button" href="/docs/integrations/spryker-glue-api/getting-started-with-apis/api-strategy.html">Learn more</a> </div> </div> </div> Thu, 25 Jun 2026 10:25:15 +0000 https://docs.spryker.com/docs/integrations/spryker-glue-api/getting-started-with-apis/getting-started-with-apis.html https://docs.spryker.com/docs/integrations/spryker-glue-api/getting-started-with-apis/getting-started-with-apis.html This document describes the project configuration to enable eProcurement systems support via PunchOut flow. ## Back Office configuration PunchOut Gateway runtime settings are managed in the Back Office under *Configuration > Integrations > Punchout Gateway*. Each setting can be set **globally** and **overridden per store**, so a store can use a value that differs from the global default. These settings are defined in [punchout_gateway.configuration.yml](https://github.com/spryker-eco/punchout-gateway/blob/main/resources/configuration/punchout_gateway.configuration.yml) and appear in the Back Office after the configuration is synchronized using command `vendor/bin/console configuration:sync`. The settings are grouped as follows. ### Logging | Setting (key) | Type | Default | Purpose | |---------------|------|---------|---------| | Enable Logging (`enable_logging`) | boolean | `false` | When enabled, the PunchOut Gateway logs incoming and outgoing PunchOut requests and responses. | ### cXML Session | Setting (key) | Type | Default | Bounds | Purpose | |---------------|------|---------|--------|---------| | Session Start URL Validity (seconds) (`start_url_validity_in_seconds`) | integer | `600` | 1–3600 | How long, in seconds, a cXML session start URL remains valid after generation. | | Session Token Length (`token_length`) | integer | `32` | 16–128 | Length, in characters, of the randomly generated cXML session token. | ## PunchOut connection configuration Configure connections through the Back Office UI. For details, see [Manage PunchOut connections](/docs/pbc/all/punchout-gateway/manage-punchout-connections.html). Demo connections for store `DE` are shipped as part of the demo shop data only, and are created during the destructive deployment. Do not use the demo data in production. If you need to recreate them, run the demo-data command provided in the [demo shop project](https://github.com/spryker-shop/b2b-demo-marketplace/blob/master/src/Pyz/Zed/PunchoutGateway/Communication/Console/PunchoutDemoConnectionCreateConsole.php): ```bash vendor/bin/console punchout-gateway:demo-connection:create ``` The rest of this section describes the persisted shape of a connection. The same fields are exposed in the Back Office form. To configure a connection manually, create a row in the `spy_punchout_connection` table: | Column | Value | Comments | |--------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fk_store` | Store ID (for example, 1) | ID of the store the customer must be logged in to. | | `name` | Human-readable label | Used only for readability | | `is_active` | `true` | Determines whether the connection can be used. | | `allow_iframe` | `true` / `false` | Enforces iframe-specific headers when the PunchOut session is active. If **~TARGET** is sent during the request, the headers are sent regardless of this value. Make sure to adjust [configuration for session cookies](/docs/pbc/all/punchout-gateway/integrate-punchout-gateway.html#support-iframe-embedding). | | `protocol_type` | `'oci'` or `'cxml'` | Flow type. | | `processor_plugin_class` | Full class name of the processor plugin. | Processor to be used. | ### OCI connection configuration OCI-specific configuration | Column | Value | Comments | |--------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `request_url` | `'/punchout-gateway/oci/my-company'` | Endpoint path the buyer posts the OCI login form to. This URL without a domain is the unique identifier of each connection, and can be anything that starts with ``https://<shop-domain>/punchout-gateway/oci/``. | | `configuration` | JSON configuration | See the *OCI Login configuration* section below. | | `protocol_type` | `'oci'` | Flow type. | | `processor_plugin_class` | Full class name of the processor plugin. | `\SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin` or a project's implementation. | The pair `protocol_type` and `request_url` must be unique, so the same `request_url` cannot be reused across stores. Column `configuration` contains JSON with the following optional keys. Override only when the value differs from the default. | Key | Default | Purpose | |-----|---------|-------------------------------------------------------------| | `usernameField` | `USERNAME` | Form field name carrying the username during login request. | | `passwordField` | `PASSWORD` | Form field name carrying the password during login request. | | `formMethod` | `POST` | HTTP method the buyer uses to post the OCI login form (`POST` or `GET`). | | `mapping` | none | Optional per-field source overrides for the outbound cart form. See [Field mapping](#field-mapping). | Additionally, configure credentials for customers who will access the shop. To do this, create rows in the `spy_punchout_credential` table: | Column | Value | Comment | |------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fk_punchout_connection` | integer | ID of the connection | | `fk_customer` | int | ID of the customer | | `username` | string | Username, that's sent in the `username` field | | `password_hash` | hashed password | Hashed password, that's sent in the `password` field. Validation happens using [password_verify](https://www.php.net/manual/en/function.password-verify.php). | | `is_active` | `true`/`false` | Active flag of this customer | Customers used for an OCI connection are expected to be fully configured in the shop so that only permitted products and prices are accessible. ### cXML connection configuration cXML-specific configuration columns: | Column | Value | Comments | |--------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | `sender_identity` | `Sender Identity` | Sender identity serves as an identifier for the connection. Unique within the database. | | `configuration` | JSON configuration | See the *configuration* section below. | | `protocol_type` | `'cxml'` | Flow type. | | `processor_plugin_class` | Full class name of the processor plugin. | `\SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultCxmlProcessorPlugin` or a project's implementation. | The `sender_identity` column value must be globally unique—each cXML system maps to exactly one connection. The sender identity is stored as a top-level column on `spy_punchout_connection`, not inside the JSON `configuration` blob. Column `configuration` contains JSON with the following keys: | Key | Required | Purpose | |-----|----------|--------------------------------------------------| | `senderSharedSecret` | yes | Shared secret used to authenticate the request. The stored value is the hash, generated with `password_hash()`. The incoming `SharedSecret` is checked against this hash with [password_verify](https://www.php.net/manual/en/function.password-verify.php). | | `mapping` | no | Optional per-field source overrides for the outbound `PunchOutOrderMessage` and custom extrinsics. See [Field mapping](#field-mapping). | For a cXML connection, no additional PunchOut-related configuration is required. The logged-in customer is identified by the `UserEmail` extrinsic field. Customers used for a cXML connection are expected to be fully configured in the shop so that only permitted products and prices are accessible. ## Field mapping Each connection can override how individual outbound protocol fields are populated, without writing a custom processor plugin. Mappings are stored in the connection's `configuration` JSON under the `mapping` key and are edited in the Back Office connection form (see [Map connection fields](/docs/pbc/all/punchout-gateway/manage-punchout-connections.html#map-connection-fields)). The mapping section is available only when editing an existing connection, not when creating one. `mapping` is an object of `targetField: sourceExpression` pairs, for example for OCI: ```json { "mapping": { "NEW_ITEM-DESCRIPTION": "item.name", "NEW_ITEM-VENDORMAT": "item.sku&\"_DE\"", "NEW_ITEM-LONGTEXT": "item.description" } } ``` - **Target field** is a protocol field identifier. For OCI, it is one of the supported `NEW_ITEM-*` fields. For cXML, it is a full cXML path, for example, `cXML.Message.PunchOutOrderMessage.ItemIn.ItemDetail.Description`, or a custom extrinsic. - **Source expression** defines where the value comes from when the cart is returned to the buyer. When a target field has no mapping, the default source documented in [PunchOut Protocols Coverage](/docs/pbc/all/punchout-gateway/punchout-protocol-coverage.html) applies. A mapping entry overrides that default. Required OCI item fields fall back to their default when not mapped; optional fields are emitted only when mapped. ### Source expression syntax The source expression is required and must match one of the following forms: | Form | Example | Result | |------|---------|--------| | Plugin expression | `item.sku` | Value read from the registered field-mapper plugin keyed `item`, traversing the `sku` path. | | Quoted constant | `"EA"` or `'EA'` | The literal text between the quotes. | | Concatenation | `item.sku&"_suffix"` | Segments joined by `&`, each a plugin expression or quoted constant, concatenated in order. | | Forced empty | `""` | An explicit empty value. | A plugin expression takes the form `pluginKey.fieldPath`, where `pluginKey` selects a registered field-mapper plugin and `fieldPath` is a dot path traversed on that plugin's transfer. Expressions are evaluated at cart-return time by `\SprykerEco\Service\PunchoutGateway\Mapper\Resolver\FieldValueResolver`. ### Field-mapper plugins Source values are resolved by plugins implementing `\SprykerEco\Service\PunchoutGateway\Dependency\Plugin\PunchoutFieldMapperPluginInterface`, registered keyed by `pluginKey` in `\SprykerEco\Service\PunchoutGateway\PunchoutGatewayDependencyProvider::getFieldMapperPlugins()`. The module ships two: | Key | Plugin | Source transfer | |-----|--------|-----------------| | `item` | `ItemTransferFieldMapperPlugin` | `ItemTransfer` of the current cart item. | | `quote` | `QuoteTransferFieldMapperPlugin` | `QuoteTransfer` of the cart. | The interface has two methods: | Method | Functionality | |--------|---------------| | `getValue` | Returns the value at `fieldName` for the given `MappingSourceTransfer`. Backs the runtime resolution of a plugin expression. | | `getPossibleValues` | Returns the list of supported dot paths, for example, `item.sku` or `quote.customer.email`. Feeds the source autosuggest in the Back Office form. | The Back Office source input is an autosuggest field served by `/punchout-gateway/source-field-suggestions/index`, which returns the union of every plugin's `getPossibleValues()`, filtered by the typed term. ### Register a custom field-mapper plugin To expose a new source root, for example, `company`, implement `PunchoutFieldMapperPluginInterface` and register it under a new key in your project's Service dependency provider: **src/Pyz/Service/PunchoutGateway/PunchoutGatewayDependencyProvider.php** ```php namespace Pyz\Service\PunchoutGateway; use Pyz\Service\PunchoutGateway\Plugin\FieldMapper\CompanyTransferFieldMapperPlugin; use SprykerEco\Service\PunchoutGateway\PunchoutGatewayDependencyProvider as SprykerEcoPunchoutGatewayDependencyProvider; class PunchoutGatewayDependencyProvider extends SprykerEcoPunchoutGatewayDependencyProvider { protected function getFieldMapperPlugins(): array { return [ ...parent::getFieldMapperPlugins(), 'company' => new CompanyTransferFieldMapperPlugin(), ]; } } ``` Source expressions can then use `company.<field>`. ### Custom extrinsics (cXML) For cXML connections, you can map values to custom `Extrinsic` elements emitted in each `ItemIn` of the `PunchOutOrderMessage`. Each extrinsic mapping has a name and a source expression. The name must match `^[A-Za-z0-9_]+$` and must not be one of the reserved user-identity names in `\SprykerEco\Shared\PunchoutGateway\PunchoutGatewayConfig::EXTRINSIC_DENY_LIST`: `User`, `UniqueUsername`, `UniqueName`, `UserId`, `UserEmail`, `UserFullName`, `UserPrintableName`, `FirstName`, `LastName`, `PhoneNumber`, `UserPhoneNumber`. An extrinsic named `ImageURL` mapped to `item.name` is stored under the target `cXML.Message.PunchOutOrderMessage.ItemIn.ItemDetail.Extrinsic.ImageURL`. ## PunchOut flow processor plugin Each PunchOut connection resolves its processor plugin at runtime using the fully qualified class name stored in `spy_punchout_connection.processor_plugin_class`. The plugin must implement one of the following interfaces: - for OCI flow - `\SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutProcessorPluginInterface` - for cXML flow - `\SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutCxmlProcessorPluginInterface`. This module provides default functionality: - \SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultCxmlProcessorPlugin - for cXML flow, - \SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin - for OCI flow. No dependency injection registration is required. The plugin is loaded at runtime. ### Creation of a custom plugin Place the plugin in your project's Zed communication layer, for example: **src/Pyz/Zed/ProjectPunchoutGateway/Communication/Plugin/PunchoutGateway/CustomOciProcessorPlugin.php** The simplest approach is to extend the default OCI plugin and override only the methods you need: ```php namespace Pyz\Zed\ProjectPunchoutGateway\Communication\Plugin\PunchoutGateway; use SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin; class CustomOciProcessorPlugin extends DefaultOciProcessorPlugin { // Override only the methods you need to customize. } ``` Set `spy_punchout_connection.processor_plugin_class` on the connection that uses this plugin to `\Pyz\Zed\ProjectPunchoutGateway\Communication\Plugin\PunchoutGateway\CustomOciProcessorPlugin`. ### Global plugin methods | Method | Called when | Functionality | |--------|--------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | `getType` | At plugin resolution | Reports the connection protocol type this plugin handles (`oci` or `cxml`). Used by `ProcessorPluginResolver` to validate that the FQCN stored on a connection matches the connection's `protocol_type`. | | `authenticate` | First step of the login flow | Finds a connection based on the setup request. Returns `null` if no valid connection is found. | | `resolveCustomer` | After a valid connection was found | Finds the customer to use for the PunchOut session. Returns `null` if no valid customer is found. | | `resolveQuote` | After a valid customer is resolved | Creates a new quote or reuses an existing one. An empty `QuoteTransfer` can be returned. | | `expandQuote` | After the quote is resolved | Allows adjusting the quote after PunchOut-specific preparations are done. | | `resolveSession` | After the quote is expanded, before the session is persisted | Additional session validation logic can be added here. | #### cXML-specific plugin methods | Method | Called when | Functionality | |--------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------| | `parseCxmlRequest` | XML was parsed and a valid connection was found. | Additional mapping of the cXML data onto setup request. | | `expandResponse` | After successful session creation | Response to the login request can be expanded, for example, with the default start URL for the customer. | ## Form handler plugin Projects extend or replace the storefront "Transfer Cart" form via plugins implementing `\SprykerEco\Yves\PunchoutGateway\Plugin\Form\PunchoutFormHandlerPluginInterface`. At render time, `PunchoutFormDataBuilder::build()` iterates the registered handlers in order and returns the result of the first whose `isApplicable()` returns `true`. The module ships two defaults, both registered in `\SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider::getPunchoutFormHandlerPlugins()`: - `\SprykerEco\Yves\PunchoutGateway\Plugin\Form\DefaultCxmlPunchoutFormHandlerPlugin` — for cXML sessions. - `\SprykerEco\Yves\PunchoutGateway\Plugin\Form\DefaultOciPunchoutFormHandlerPlugin` — for OCI sessions. ### Plugin methods | Method | Called when | Functionality | |--------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isApplicable` | Before each render of the widget | Returns `true` when the quote's PunchOut session matches this handler's protocol. | | `handle` | After `isApplicable()` returned `true` | Builds the `PunchoutFormDataTransfer` carrying the action URL and all hidden form fields, or returns `null` when the form cannot be built (for example, missing session data). | ### Register a custom handler Place the plugin in your project's Yves layer, for example: **src/Pyz/Yves/ProjectPunchoutGateway/Plugin/Form/CustomCxmlPunchoutFormHandlerPlugin.php** Then register it before the defaults so it takes precedence for the same protocol: **src/Pyz/Yves/PunchoutGateway/PunchoutGatewayDependencyProvider.php** ```php namespace Pyz\Yves\PunchoutGateway; use Pyz\Yves\ProjectPunchoutGateway\Plugin\Form\CustomCxmlPunchoutFormHandlerPlugin; use SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider as SprykerEcoPunchoutGatewayDependencyProvider; class PunchoutGatewayDependencyProvider extends SprykerEcoPunchoutGatewayDependencyProvider { protected function getPunchoutFormHandlerPlugins(): array { return [ new CustomCxmlPunchoutFormHandlerPlugin(), ...parent::getPunchoutFormHandlerPlugins(), ]; } } ``` ## Punchout-specific security header expander plugin At PunchOut session start, Yves applies protocol-specific `Content-Security-Policy` (CSP) directives to allow the Storefront to be embedded and to post back to the buyer's procurement system. Directive generation is delegated to plugins implementing `\SprykerEco\Yves\PunchoutGateway\Dependency\Plugin\PunchoutSecurityHeaderExpanderPluginInterface`. `PunchoutSecurityHeaderSessionWriter` walks the registered plugins and accumulates their directives for the active session once, persisting the value into the session. When `spy_punchout_connection.allow_iframe` is `true`, the correct CSP headers are included in each response. By default, we provide an OCI-specific plugin only: - `\SprykerEco\Yves\PunchoutGateway\Plugin\SecurityHeader\DefaultOciSecurityHeaderExpanderPlugin` — adds `frame-ancestors` to the CSP for OCI sessions when the OCI login carries a `~TARGET` form field. ### Plugin method | Method | Functionality | |--------|-----------------------------------------------------------------------------------------------------------------------| | `expand` | Appends protocol-specific CSP directive strings to the given list. Implementations must not add duplicate directives. | ### Register a custom expander In case your system requires additional Punchout-specific security headers, add your plugin to the Yves dependency provider. **src/Pyz/Yves/PunchoutGateway/PunchoutGatewayDependencyProvider.php** ```php namespace Pyz\Yves\PunchoutGateway; use Pyz\Yves\ProjectPunchoutGateway\Plugin\SecurityHeader\CustomCxmlSecurityHeaderExpanderPlugin; use SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider as SprykerEcoPunchoutGatewayDependencyProvider; class PunchoutGatewayDependencyProvider extends SprykerEcoPunchoutGatewayDependencyProvider { protected function getPunchoutSecurityHeaderExpanderPlugins(): array { return [ ...parent::getPunchoutSecurityHeaderExpanderPlugins(), new CustomCxmlSecurityHeaderExpanderPlugin(), ]; } } ``` ## Session-in-quote expander plugin `PunchoutQuoteExpander` (Zed) loads the PunchOut session that belongs to the current quote and runs it through every registered `\SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutSessionInQuoteExpanderPluginInterface` before stamping it on the `QuoteTransfer`. Use this extension point to enrich or override PunchOut session fields based on the quote (for example, to copy a project-specific field onto the session before it is persisted with the cart). ### Plugin methods | Method | Called when | Functionality | |--------|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------| | `isApplicable` | For each plugin, before `expand()` runs | Returns `true` when the plugin should run for the given session/quote combination. | | `expand` | After `isApplicable()` returned `true` | Expands the `PunchoutSessionTransfer` before it is assigned to the `QuoteTransfer`. | ## Default implementations This section describes the behavior of the two shipped default processor plugins and the storefront "Transfer Cart" widget for each lifecycle step. Use it to understand what you get out-of-the-box and to identify which plugin method to override when customising. ### Shared behavior Both `DefaultOciProcessorPlugin` and `DefaultCxmlProcessorPlugin` rely on `QuoteCreator` to stamp the following fields on every new quote: - **Store** — resolved from `spy_punchout_connection.fk_store`. - **Currency** — set to the default currency of the resolved store. ### OCI **Customer identification** `OciCustomerResolver` looks up the customer by the `idCustomer` that is already on the connection transfer. That value is stamped during authentication: `PunchoutOciAuthenticator` matches the username and password from the OCI form fields against `spy_punchout_credential` and, on success, writes `connection.idCustomer`. The buyer identity therefore comes entirely from the credential record — nothing from the buyer's login payload is used. Override `resolveCustomer` on the processor plugin to source the customer differently (for example, from a custom form field). **Quote identification** `OciPunchoutQuoteFinder` always returns a fresh empty `QuoteTransfer` with `DEFAULT_QUOTE_NAME`. There is no session-to-quote lookup on OCI login; every login starts a new cart. Store and currency are set by `QuoteCreator` as described in the shared behavior section above. Override `resolveQuote` to reuse a per-customer cart across sessions. **Quote fill with items** OCI login does not carry item data. `DefaultOciProcessorPlugin::expandQuote` is a pass-through and leaves the quote empty. Items are transferred back to the buyer's procurement system via the storefront form POST (see "Transfer Cart button" below), not populated during login. **Transfer Cart button** `DefaultOciPunchoutFormHandlerPlugin` (registered in `\SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider`) makes the button visible when the current quote has a PunchOut session whose `punchoutData.ociLoginRequest` is not `null`. When applicable, the action URL is taken from the `HOOK_URL` form field of the OCI login request (validated to start with `https://` at session creation time). The hidden form fields are OCI-flat `NEW_ITEM-…` key/value pairs produced by `OciFormFieldBuilder`. The button is not rendered when no punchout session exists on the quote, when the session was created by a cXML login, or when no handler plugin is registered for the Yves factory. ### cXML **Customer identification** `CxmlCustomerResolver` reads the `Extrinsic[name="UserEmail"]` field from the parsed `PunchOutSetupRequest` and resolves the customer via `CustomerFacade::getCustomer` by email. Connection authentication is a separate step that runs first: `PunchoutCxmlAuthenticator` verifies the `senderSharedSecret` from the cXML header against the connection record using `password_verify`. If the `UserEmail` extrinsic is absent or empty, `resolveCustomer` returns `null` and the session is rejected. Override `resolveCustomer` to read identity from a different extrinsic or from a custom header field. **Quote identification** `CxmlPunchoutQuoteFinder` uses `BuyerCookie` from the `PunchOutSetupRequest` to look up an existing PunchOut session via `PunchoutGatewayRepository::findPunchoutSessionByBuyerCookie`. When a session is found, the linked quote is reused — allowing the buyer to resume an in-progress cart. If the found quote belongs to a different store than the current connection's `idStore`, the old quote is deleted and a new empty one is created. When `BuyerCookie` is missing or no session matches, a new `DEFAULT_QUOTE_NAME` quote is returned. Store and currency are then set by `QuoteCreator`. Override `resolveQuote` to change cookie-matching rules or to support cross-store quote reuse. Quote is always presented as an empty one for a customer after session start. **Transfer Cart button** `DefaultCxmlPunchoutFormHandlerPlugin` makes the button visible when the current quote has a PunchOut session whose `punchoutData.cxmlSetupRequest` is not `null`. The action URL is `punchoutSession.browserFormPostUrl`, captured from the original `PunchOutSetupRequest.BrowserFormPost.URL` at login time. A single hidden field (`CXML_FORM_FIELD_NAME`) carries the `PunchOutOrderMessage` built by `PunchoutGatewayService::buildCxmlPunchoutOrderMessage`. The button is not rendered when no punchout session exists, when the session was created by an OCI login, or when no handler plugin is registered. ### Widget visibility summary `PunchoutCartWidget` is always instantiated on pages where it is embedded. Actual form visibility is determined by `PunchoutFormDataBuilder::build()`, which calls plugins of interface `PunchoutFormHandlerPluginInterface` and returns the result of the first whose `isApplicable()` returns `true`. The Twig template renders the `<form>` and submit button only when `formData` is not `null` and `formData.actionUrl` is not empty. If you register a custom handler plugin, place it before the default plugins in the dependency provider so it takes precedence for the same protocol. For OCI flow, the button is rendered for the empty cart as well to allow empty-order return to the eProcurement platform. For cXML flow, no button is rendered for the empty cart. This behavior will be improved in the next version. ## PunchOut endpoints `PunchoutGatewayRouteProviderPlugin` (Yves) registers five routes consumed by the buyer's eProcurement system and by the buyer's browser: | Method | Path | Purpose | |--------|--------------------------------------------|-----------------------------------------------------------------------------------------------------------| | `POST` | `/punchout-cxml-setup` | Inbound cXML `PunchOutSetupRequest` for the single-connection-per-store case. | | `GET` | `/punchout-cxml-start?session={token}` | Buyer's browser opens this URL with the session token returned in the synchronous `PunchOutSetupResponse`. | | `POST` | `/punchout-gateway/oci/{connectionSlug}` | Inbound OCI login form (default method). | | `GET` | `/punchout-gateway/oci/{connectionSlug}` | Inbound OCI login when the connection is configured with `formMethod=GET`. | The slug accepted in OCI routes matches `[a-zA-Z0-9_-]+`. ## cXML session start lifecycle The cXML flow is a two-step handshake: 1. The buyer's procurement system `POST`s a `PunchOutSetupRequest` to a cXML setup route. The shop authenticates the request, resolves the customer and quote, persists a `spy_punchout_session` row, and replies synchronously with a `PunchOutSetupResponse` whose `StartPage/URL` contains a one-shot session token: ``https://<shop-domain>/punchout-cxml-start?session=<token>``. 2. The buyer's browser follows that URL. `CxmlController::startAction` reads the token from the `session` query parameter, looks up the session, logs the customer in via `LoginModel::loginCustomerFromSession`, stores the protocol-specific Content Security Policy fragment via `PunchoutSecurityHeaderSessionWriter`, and redirects to the shop. Two settings control this handshake: | Setting | Default | Bounds | Purpose | |---------|---------|--------|---------| | `getCxmlSessionTokenLength()` | `32` | 16–128 | Length of the generated session token. | | `getCxmlSessionStartUrlValidityInSeconds()` | `600` | 1–3600 | How long the start URL remains valid after the synchronous response is sent. | Both are exposed in the Back Office settings panel under *Configuration > Integrations > Punchout Gateway*. See [Back Office configuration](#back-office-configuration). ## spy_punchout_session table The session table is created by `propel:install` (see [Set up the database schema](/docs/pbc/all/punchout-gateway/integrate-punchout-gateway.html#set-up-the-database-schema)). It links one PunchOut login attempt to the resulting cart: | Column | Type | Comment | |--------|------|---------| | `id_punchout_session` | integer, PK | Auto-increment. | | `fk_quote` | integer, FK | Quote that belongs to this session. Cascade-deletes with the quote. | | `fk_customer` | integer, FK | Customer logged in by the PunchOut handshake. Cascade-deletes with the customer. | | `fk_punchout_connection` | integer, FK | Connection that produced this session. Cascade-deletes with the connection. | | `buyer_cookie` | varchar(256) | cXML `BuyerCookie` used to resume the cart across logins. | | `browser_form_post_url` | text | `BrowserFormPost.URL` (cXML) or `HOOK_URL` (OCI). The cart return form posts here. | | `operation` | varchar(32) | cXML operation that started the session (`create` or `edit`). Empty for OCI. | | `session_token` | varchar(255), unique | One-shot token embedded in the cXML start URL. | | `valid_to` | timestamp | Token expiry; computed from `getCxmlSessionStartUrlValidityInSeconds()`. | | `session_data` | text | Serialized `PunchoutSessionData` (cXML setup request or OCI login request). | | `created_at`, `updated_at` | timestamp | Maintained by the timestampable behavior. | Wed, 24 Jun 2026 10:35:19 +0000 https://docs.spryker.com/docs/pbc/all/punchout-gateway/project-configuration-for-punchout-gateway.html https://docs.spryker.com/docs/pbc/all/punchout-gateway/project-configuration-for-punchout-gateway.html This document describes how to integrate the PunchOut Gateway module into a Spryker shop. ## 1. Install the module Install the PunchOut Gateway module using Composer: ```bash composer require spryker-eco/punchout-gateway:^1.1.0 ``` ## 2. Configure the module To control logging through the AWS Parameter Store, add the following optional configuration: **config/Shared/config_default.php** ```php use SprykerEco\Shared\PunchoutGateway\PunchoutGatewayConstants; $config[PunchoutGatewayConstants::ENABLE_LOGGING] = getenv('PUNCHOUT_GATEWAY_ENABLE_LOGGING') ?: false; ``` ### Configuration constants | Constant | Description | Default | |----------|-------------------------------------------------------------------------------------------------------------------------------------------------|----------| | `ENABLE_LOGGING` | Enables or disables logging for PunchOut Gateway. | `false` | ### Logging When logging is enabled, the module emits structured entries through `\SprykerEco\Shared\PunchoutGateway\Logger\PunchoutLoggerInterface`. The shipped implementation `PunchoutLogger` writes to the standard Spryker log channels and covers, among others, request reception and parsing, authentication attempts and outcomes, response generation, quote and session creation, and uncaught throwables. When logging is disabled, the resolver returns `NullPunchoutLogger` and all calls become no-ops. ## 3. Additional module configuration `src/Pyz/Zed/PunchoutGateway/PunchoutGatewayConfig.php` provides the following configuration methods: | Method | Default | Description | |--------|---------|-------------| | `isLoggingEnabled()` | `false` | Enables or disables PunchOut Gateway logging. | | `getCxmlSessionStartUrlValidityInSeconds()` | `600` | Validity period of the cXML session start URL in seconds. | | `getOciDefaultStartUrl()` | `'/'` | Default redirect URL after OCI session start. | | `getCxmlSessionTokenLength()` | `32` | Length of the generated cXML session token. | Some values can be changed at runtime in the Back Office under *Configuration > Integrations > Punchout Gateway*, both globally and per store. For a description of each setting, see [Back Office configuration](/docs/pbc/all/punchout-gateway/project-configuration-for-punchout-gateway.html#back-office-configuration). These settings are defined in [punchout_gateway.configuration.yml](https://github.com/spryker-eco/punchout-gateway/blob/main/resources/configuration/punchout_gateway.configuration.yml) and appear in the Back Office after you synchronize the configuration. Run to register them: ```bash vendor/bin/console configuration:sync ``` ## 4. Update Quote configuration Update `QuoteConfig` to allow the PunchOut session field to be saved with the quote. **src/Pyz/Zed/Quote/QuoteConfig.php** ```php use Generated\Shared\Transfer\QuoteTransfer; public function getQuoteFieldsAllowedForSaving(): array { return array_merge(parent::getQuoteFieldsAllowedForSaving(), [ // ... QuoteTransfer::PUNCHOUT_SESSION, ]); } ``` ## 5. Set up the database schema Install the database schema: ```bash vendor/bin/console propel:install ``` This creates the following tables: | Table | Description | |-------|-------------| | `spy_punchout_connection` | Stores PunchOut connection configuration per store. | | `spy_punchout_credential` | Stores credentials (username/password) linked to a connection and customer. | | `spy_punchout_session` | Stores active PunchOut sessions linked to a quote. | ## 6. Generate transfer objects Generate transfer objects for the module: ```bash vendor/bin/console transfer:generate ``` ## 7. Register plugins ### Register the Quote expander plugin Add the PunchOut session expander plugin: **src/Pyz/Zed/Quote/QuoteDependencyProvider.php** ```php use SprykerEco\Zed\PunchoutGateway\Communication\Plugin\Quote\PunchoutSessionQuoteExpanderPlugin; protected function getQuoteExpanderPlugins(): array { return [ // ... new PunchoutSessionQuoteExpanderPlugin(), ]; } ``` ### Register the route provider plugin Add the route provider plugin: **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php use SprykerEco\Yves\PunchoutGateway\Plugin\Router\PunchoutGatewayRouteProviderPlugin; protected function getRouteProvider(): array { return [ // ... new PunchoutGatewayRouteProviderPlugin(), ]; } ``` ### Register the security header expander plugin Add the security header expander plugin: **src/Pyz/Yves/Application/ApplicationDependencyProvider.php** ```php use SprykerEco\Yves\PunchoutGateway\Plugin\Application\PunchoutSecurityHeaderExpanderPlugin; protected function getSecurityHeaderExpanderPlugins(): array { return [ // ... new PunchoutSecurityHeaderExpanderPlugin(), ]; } ``` ### Support iframe embedding If your eProcurement system requires embedding into an iframe, you must also adjust this variable in the deploy file for your environments: ```yml image: environment: SPRYKER_YVES_SESSION_COOKIE_SAMESITE: 'none' ``` ## 8. Register the cart widget Add the PunchOut cart widget: **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php use SprykerEco\Yves\PunchoutGateway\Widget\PunchoutCartWidget; protected function getGlobalWidgets(): array { return [ // ... PunchoutCartWidget::class, ]; } ``` The widget is rendered wherever it is embedded by the cart template. If your project uses the stock `spryker-shop/cart-page` template, embed it inside `SprykerShop/Yves/CartPage/Theme/default/templates/page-layout-cart/page-layout-cart.twig` (or your override) so that the "Transfer Cart" button is shown on the cart page. The following example shows `PunchoutCartWidget` usage: ```twig {% raw %} {% widget 'PunchoutCartWidget' args [data.cart] only %}{% endwidget %} {% endraw %} ``` ## 9. Import glossary data The module provides glossary translations used by the PunchOut flow. **Option 1: Import using the module's configuration file** ```bash vendor/bin/console data:import --config=vendor/spryker-eco/punchout-gateway/data/import/punchout-gateway.yml ``` **Option 2: Copy file content and import individually** Copy content from `vendor/spryker-eco/punchout-gateway/data/import/*.csv` to the corresponding files in `data/import/common/common/`. Then run: ```bash vendor/bin/console data:import glossary ``` ## 10. Translations for the Back Office The module ships Zed translations for the Back Office UI in `vendor/spryker-eco/punchout-gateway/data/translation/Zed/en_US.csv` and `de_DE.csv`. They are picked up by the standard Zed translator on the next request, so no separate import step is required. To override a label, add an entry with the same key to your project's Zed translation file. ## Verify the integration After completing the steps above: - Open *Punchout Connections* in the Back Office. The grid should render empty until you create your first connection. - Create your first connection, following [Manage PunchOut connections](/docs/pbc/all/punchout-gateway/manage-punchout-connections.html), and confirm that DB table `spy_punchout_connection` and the grid both reflect it. - as a part of our Demoshop, we provide the following command `vendor/bin/console punchout-gateway:demo-connection:create`, which inserts demo cXML and OCI connections for `DE` store. ## Additional links - [Manage PunchOut connections](/docs/pbc/all/punchout-gateway/manage-punchout-connections.html) — Back Office workflow for connections and credentials. - [Project configuration for PunchOut Gateway](/docs/pbc/all/punchout-gateway/project-configuration-for-punchout-gateway.html) — connection columns, processor and form-handler plugins, endpoints. - [PunchOut Protocols Coverage](/docs/pbc/all/punchout-gateway/punchout-protocol-coverage.html) — cXML and OCI field-by-field mapping. Wed, 24 Jun 2026 10:35:19 +0000 https://docs.spryker.com/docs/pbc/all/punchout-gateway/integrate-punchout-gateway.html https://docs.spryker.com/docs/pbc/all/punchout-gateway/integrate-punchout-gateway.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). ## Expanded B2B commerce capabilities ### Self-Service Portal models for asset-based catalogs {% include badge.html type="feature" %} Self-Service Portal (SSP) models help operators manage complex equipment structures and help customers find compatible spare parts and service products faster in asset-based catalogs.  **What are SSP models?** SSP models let you group multiple assets into a single product family (for example, a machine type or series). Assets in the SSP are now directly connected to the product catalog, including compatible spare parts and service offerings, making the Self-Service Portal fully transactional. For each model, a curated list of compatible spare parts and services can be maintained. When a customer browses the catalog or opens a product detail page, results are automatically filtered to show only items compatible with the selected model or asset, enabling accurate identification and immediate purchase. **Key capabilities:** - Group assets that belong to the same machinery type or generation. - Maintain compatibility at the model level instead of the individual asset level. - Assign spare part lists to models so buyers see only relevant products. - Filter the storefront catalog by model, asset, serial number, or model code. - Run compatibility checks from the product detail page. - Support transactional self-service so customers purchase the correct items faster. **Business benefits:** - Improve spare part identification accuracy in self-service journeys. - Reduce maintenance effort for asset-to-product mapping. - Speed up after-sales purchases with asset-specific filtering. - Scale after-sales revenue with automation and self-service. Models is available in the Self-Service Portal Back Office and Storefront. **Documentation:** - [Self-Service Portal Models](/docs/pbc/all/self-service-portal/latest/ssp-model-management-feature-overview) - [Self-Service Portal Asset Based Catalog](/docs/pbc/all/self-service-portal/latest/ssp-asset-based-catalog-feature-overview) - [Self-Service Portal](/docs/pbc/all/self-service-portal/latest/self-service-portal) ### Merchant Portal file-based product import is now generally available {% include badge.html type="feature" %} {% include badge.html type="improvement" %} File-based product import in Merchant Portal moves from Early Access to General Availability, with reliability and UX improvements based on customer feedback.  **Key capabilities** - Provide clear post-import results (success and errors) in the UI or as a downloadable CSV. - Strengthen validations and safeguards to reduce failed imports and incorrect updates. - Improve import consistency for production usage, including better messaging and translations where applicable. **Business benefits** - Faster merchant onboarding and ongoing catalog maintenance at scale. - Lower support effort thanks to clearer feedback and import logs. - Higher confidence running bulk imports in production environments. **Documentation:** - [Merchant Portal Import Products](/docs/pbc/all/product-information-management/latest/marketplace/manage-in-the-merchant-portal/import-products-ui) - [Merchant Portal Import Product Offers](/docs/pbc/all/offer-management/latest/marketplace/import-offers-ui) - [Install Merchant Portal Product Data Import](/docs/pbc/all/product-information-management/latest/marketplace/install-and-upgrade/install-features/install-the-merchant-product-data-import-feature) - [Install Product Offer Data Import](/docs/pbc/all/offer-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-merchant-portal-product-offer-data-import-feature) ### Merchant Self-Registration {% include badge.html type="feature" %} Merchant onboarding is simplified with a storefront entry point while keeping marketplace quality and compliance under control through Back Office review and approval.  **Key capabilities:** - Added a storefront-led merchant self-registration flow, allowing prospective merchants to submit an application which can be reviewed and approved in Back Office before merchant entities and users are created. **Business benefits:** - Reduced manual onboarding effort and improved consistency of merchant intake. - Faster and more controlled merchant onboarding for marketplace operators. **Documentation:** - [Merchant Self-Registration](/docs/pbc/all/merchant-management/latest/marketplace/merchant-self-registration-feature-overview) - [Install Merchant Self-Registration](/docs/pbc/all/merchant-management/latest/marketplace/install-and-upgrade/install-features/install-the-merchant-self-registration-feature) ### Agent assist order traceability {% include badge.html type="feature" %} {% include badge.html type="improvement" %} Order traceability for Agent Assist flows is improved so operations and support teams can quickly see who submitted an order on behalf of a customer. **Key capabilities:** - Back Office now records and displays the submitting agent email for orders placed via Agent Assist, improving traceability and follow-up efficiency. **Business benefits:** - Faster issue resolution and clearer ownership for agent-created orders. - Improved auditability for Agent Assist flows. **Documentation:** - [Agent Assist](/docs/pbc/all/user-management/latest/base-shop/agent-assist-feature-overview#setting-up-an-agent-user) - [Install Agent Assist](/docs/pbc/all/user-management/latest/base-shop/install-and-upgrade/install-the-agent-assist-feature#install-feature-core) ### Merchant Portal dashboard improvements {% include badge.html type="feature" %} {% include badge.html type="improvement" %} Merchant day to day catalog work is simplified in Merchant Portal by adding a clearer entry point to product management directly from the dashboard.  **Key capabilities** - Added a Products widget to the Merchant Portal dashboard to improve discoverability of product management. **Business benefits** - Faster access to core catalog workflows for merchants. - Less navigation effort for merchants managing large assortments. ### Storefront merchant profile improvements {% include badge.html type="feature" %} {% include badge.html type="improvement" %} Storefront discovery is improved by making it easier for buyers to navigate from a merchant profile to that merchant's products with the right catalog filters already applied. **Key capabilities** - Added a "Shop Merchant Products" button on the merchant profile page that opens the product catalog with an active merchant filter. **Business benefits** - Faster product discovery for buyers shopping by merchant. - Smoother path from merchant pages to relevant catalog results. ### Clearer UI in Back Office and Storefront {% include badge.html type="improvement" %} Core UI patterns are made more consistent to improve scanability, reduce cognitive load, and provide clearer next steps in common workflows. **Key capabilities** - Introduced a global empty state component for tables with two variants: - Implemented a semantic status pill color system (success, warning, error, neutral) for tables and internal pages, with one-line enforcement for better scanability. - Replaced blocking Storefront notification banners with floating toast notifications (stacked, auto-dismiss, responsive positioning). **Business benefits** - Faster scanning and fewer mistakes when working with large datasets. - Clearer guidance when tables are empty, improving task completion. - Less disruptive Storefront messaging that keeps customers in context. ## Spryker AI: Built for Real Enterprise Commerce ### AI Foundation {% include badge.html type="early-access" %} AI Foundation is a provider-agnostic integration layer for building AI powered commerce capabilities in a consistent, maintainable way. **Key capabilities:** - New AiFoundation module compatible with Spryker architecture and existing AI related Eco packages. - Multi provider support through a single interface (for example OpenAI, Azure OpenAI, AWS Bedrock, Google Gemini, Anthropic, local providers). - Prompt based client method that supports file attachments for richer use cases. **Business benefits:** - Faster delivery of AI enabled commerce features through a reusable platform layer. - Provider freedom: adopt or switch AI providers without rewriting feature logic, and choose the best provider and model per use case without rewriting code. - Best fit provider per use case: use different providers and models for different needs. - Lower maintenance effort by centralizing AI integration patterns and configuration. **Documentation:** - [AI Foundation](/docs/pbc/all/ai-foundation/latest/ai-foundation.html) - [Use the AiFoundation module](/docs/pbc/all/ai-foundation/latest/ai-foundation.html) ### Spryker AI Commerce: Back Office Smart Product Management {% include badge.html type="feature" %} {% include badge.html type="early-access" %} {% include badge.html type="improvement" %} Back Office Smart Product Management now uses AI Foundation as its AI integration layer, replacing the previous direct OpenAI coupling. This gives customers provider and model choice while keeping existing Smart Product Management AI capabilities working. <figure class="video_container"> <video width="100%" height="auto" controls aria-label="Smart PIM Product Translations"> <source src="https://spryker.s3.eu-central-1.amazonaws.com/docs/About/all/releases/release-notes-202512.0.md/smart-pim-translations.m4v" type="video/mp4"> </video> </figure> **Key capabilities:** - Replace direct OpenAI integration in with AI Foundation as the unified AI layer. - Enable provider and model selection based on customer needs (for example different providers for cost, latency, data residency, or model capabilities). **Business benefits:** - Protects existing customer functionality while enabling a standardized path for future AI enhancements. - Reduces future integration effort and maintenance overhead for AI driven product management capabilities. **Documentation:** - [Smart Product Management](/docs/pbc/all/product-information-management/latest/base-shop/third-party-integrations/smart-product-management/smart-product-management) - [Install Smart Product Management](/docs/pbc/all/product-information-management/latest/base-shop/third-party-integrations/smart-product-management/install-smart-product-management) ### Spryker AI Dev SDK {% include badge.html type="early-access" %} The AI Dev SDK improves local AI assisted development with an MCP server, Spryker aware context tools, and prompt library integration, so developers and AI assistants can work with accurate project information and reuse the same prompts across teams. ### Key capabilities - Run a local MCP server for your Spryker project and extend it with custom tools and prompts. - Give AI assistants access to Spryker contracts and data structures to reduce guesswork and implementation errors. - Support OMS flow exploration by showing an order's current state and valid transitions, or listing transitions from any given state. - Reuse and generate prompts from the shared Prompt Library via a typed PHP API. - Keep console output integration friendly with quiet execution. **Documentation:** - [AI Dev SDK Overview](/docs/dg/dev/ai/ai-dev/ai-dev-overview.html) - [Configure the AiDev MCP server](/docs/dg/dev/ai/ai-dev/ai-dev-mcp-server.html) ## Open Architecture for the upcoming Innovation ### Reduced boilerplate via Symfony Dependency Injection support {% include badge.html type="feature" %} Spryker uses the Dependency Inversion Principle to reduce tight coupling, improve unit testability, and provide a clear, extensible architecture. This approach enables autowiring and reduces the need for repetitive `Factory` and `DependencyProvider` wiring. This approach streamlines development and remains compatible with Symfony Dependency Injection conventions and tooling. <figure class="video_container"> <video width="100%" height="auto" controls aria-label="Symfony Dependency Injection and Architecture Overview"> <source src="https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202512/symfony_di.mp4" type="video/mp4"> </video> </figure> **Key capabilities:** - Reduced manual dependency wiring in your project code. - Improved compatibility with Symfony bundles and Symfony Dependency Injection tooling, such as container introspection. Tools like `debug:container` help you visualize all services. - Self-explanatory, declarative configuration. - High performance through compiled and cached dependency injection. **Business benefits:** - **Code autowiring**: Reduce the boilerplate code you write and maintain by using Symfony Dependency Injection to automatically connect application components. - **Faster feature delivery** by reducing repetitive scaffolding. - **Easier onboarding** for developers who are already familiar with Symfony conventions. **Documentation:** - [Symfony Dependency Injection](/docs/dg/dev/architecture/dependency-injection.html) - [Symfony Bundles in Spryker](/docs/dg/dev/architecture/symfony-bundles.html) ### API Platform {% include badge.html type="early-access" %} {% include badge.html type="feature" %} The **API Platform** integration allows you to define API resources declaratively and automatically generate standards-compliant APIs with minimal manual effort. It reduces boilerplate, enforces consistency, and accelerates API development.  **Key capabilities:** - **Declarative API definition**: Define API resources using simple YAML schemas instead of writing repetitive controller and transfer logic. - **Automatic endpoint generation**: Generate endpoints with built-in validation, pagination, and serialization that are ready for production use. - **OpenAPI documentation**: Interactive OpenAPI documentation is generated automatically and stays in sync with your API definitions. - **Consistent data contracts**: Enforce uniform data contracts and operation-specific validation rules across all APIs. - **Clear separation of concerns**: Separate read and write logic using providers and processors for better maintainability and extensibility. **Business benefits:** - **Faster API development**: Reduce boilerplate and repetitive scaffolding, enabling faster feature delivery. - **Easier onboarding**: Simplify API development for new teams and partners by providing clear documentation and structured guidance. **Documentation:** - [API Platform](/docs/dg/dev/architecture/api-platform.html) ### API tooling and integration documentation improvements {% include badge.html type="improvement" %} To make API development and partner onboarding easier, the following improvements are introduced: - Enhanced the API documentation to be more structured and usable, with clearer terminology and guidance for integrations, including better support for exploring APIs and understanding data models. - Enhanced documentation of the **Spryker data model**, including products, attributes, prices, and orders. - Added a publicly available **Postman API collection** package, organized around practical "happy path" use cases and environments. <figure class="video_container"> <video width="100%" height="auto" controls aria-label="Interactive API documentation walkthrough"> <source src="https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202512/interactive_API_docs.mp4" type="video/mp4"> </video> </figure> **Key capabilities:** - Ready-to-run Postman collections for common API flows. - Improved documentation structure and integration guidance for solution partners. **Business benefits:** - Faster API adoption and easier onboarding for developers and partners. - Reduced integration effort and fewer misunderstandings for partners and new teams. **Documentation:** - [Integrations Documentation Portal](/docs/integrations/integrate-with-spryker.html) - [Integrations Catalog](/docs/integrations/third-party-integrations.html) - [Interactive API Playground](/docs/integrations/spryker-glue-api/storefront-api/api-references/storefront-api-marketplace-b2b-demo-shop-reference.html). - [API reference with data model descriptions](/docs/integrations/spryker-glue-api/backend-api/api-references/backend-api-marketplace-b2b-demo-shop-reference.html). Expand each resposne to learn more about each field. - [Postman Collections](https://github.com/spryker-community/glue-postman-collections) ### Publish & Synchronize stability and scalability improvements {% include badge.html type="improvement" %} Multiple enhancements improve the robustness and transparency of Publish & Synchronize processing, especially when you operate in high-volume environments. **Key capabilities:** - Better resource monitoring and utilization for workers. - Reduced noise from excessive INFO logs and more meaningful statistics and log output. - Improved handling of slow queues through configurable waiting to avoid blocking other processing. - Fixes for known stability issues reported across multiple customers. - Improved error logging in the `queue:worker:start` output, including the queue name, failed message content, and exception chain. - Cleaner processing output that suppresses "all zeros" lines and logs data only when metrics indicate work. - Better ability to adjust processing batch size per queue to isolate problematic messages. **Business benefits:** - More stable P&S execution under load. - Easier scaling and debugging of complex event-driven catalog and offer updates. - Reduced operational overhead for teams running large data volumes. - Faster incident diagnosis for queue-related failures. - Reduced log noise while keeping meaningful operational insights. **Documentation and module releases:** If you are using older versions, we recommend that you update to the referenced releases. - [Implement Publish and Synchronization](/docs/dg/dev/backend-development/data-manipulation/data-publishing/implement-publish-and-synchronization.html) - [Metrics and resource-aware worker configuration](/docs/dg/dev/backend-development/data-manipulation/event/configure-event-queues.html#metrics-and-resource-aware-worker-configuration) - [Newest Publish & Synchronize modules](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html#use-the-newest-modules) - [Split heavy entities from publish and event queues](https://api.release.spryker.com/release-group/6027) - [Batch processing of Propel entities](/docs/dg/dev/guidelines/performance-guidelines/performance-guidelines-batch-processing-propel-entities.html) ### Performance improvements {% include badge.html type="improvement" %} Rendering of product items, cart pages, URL resolution database queries, and checkout shipment type loading has been optimized. **Key capabilities:** - Reduced repeated per-item loading patterns that previously caused multiple separate search calls for the cart, catalog listings, and PDP carousels. - Improved widget and template behavior to avoid N-times Elasticsearch request patterns in common flows. - Targeted cart performance improvements for large baskets. - Eliminated unnecessary case-insensitive comparisons using `UPPER()` where the database collation is already case-insensitive. - Improved performance for URL lookups in large datasets (reduces long-running queries and CPU pressure). - Improved checkout performance by introducing a bulk shipment type list storage plugin (`spryker/shipment-type-storage:1.2.0`). **Business benefits:** - Faster page loads on high-traffic pages such as the cart, catalog, PDP, and checkout. - Lower search infrastructure cost by cutting unnecessary requests. - More predictable performance for customers with large carts and catalogs. - Lower database CPU utilization. - Faster request handling for URL-heavy flows (storefront and merchant portal routing scenarios). **Documentation:** - [Product review performance](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html#product-review-performance) - [Cart performance configuration](/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html#cart-page-performance-configuration) - [Shipment type performance configuration](/docs/pbc/all/carrier-management/latest/base-shop/install-and-upgrade/install-features/install-the-shipment-feature.html#shipment-type-storage-performance-fix) **Module Important technical releases:** - [Cart page performance optimization](https://api.release.spryker.com/release-group/6107) - [UPPER() function optimization for URL lookups](https://api.release.spryker.com/release-group/6124) - [Checkout shipment type loading optimization](https://api.release.spryker.com/release-group/5736) ### Reliability improvements {% include badge.html type="improvement" %} **Key capabilities:** - **Glue API** - Authentication is improved to avoid overloading JWT token payloads with large, mutable, session-relevant data, such as fine-grained permissions. - The API supports up-to-date permission and state resolution without relying on token reissuance. - **Search**: Error handling in full-text search is improved to ensure that unexpected failures are logged and that users receive a consistent fallback experience. - **OMS**: Order Management System processing is hardened against race conditions in which lock behavior can be unsafe in transactional or fast-response environments. **Business benefits:** - **Glue API**: Reduced risk of header-size-related failures in integrations that use extensive permission sets. - **Search**: Faster production troubleshooting and fewer silent failures. - **OMS**: - Fewer hard-to-reproduce concurrency issues in payment and order update flows. - Increased consistency of order state transitions under parallel event processing. **Module releases:** - [Glue API: Authentication improvements](https://api.release.spryker.com/release-group/6095) - [Search: Improved error handling](https://api.release.spryker.com/release-group/6147) - [OMS: Improved concurrency handling](https://api.release.spryker.com/release-group/5963) ### Infrastructure and runtime upgrades {% include badge.html type="improvement" %} Spryker updates its database support strategy to align MySQL and MariaDB versions with currently supported long-term support (LTS) releases. This change addresses the end of support for MySQL 5.7 and mitigates compatibility issues in production environments. The update also includes changes to other components, such as PHP, RabbitMQ, and Bootstrap. **Key capabilities:** - Aligns supported **MySQL versions with modern LTS releases**, including MySQL 8.4. - Continues support for **MariaDB 11.8** while ensuring secure and up-to-date LTS versions. Incremental rollouts are planned for early 2026. - Enables **Redis compression by default** in demoshops to reduce memory footprint and improve cache efficiency. - Ensures **PHP 8.4 readiness** through updates across modules and supporting tooling. - Adds **RabbitMQ 4.1 support** to keep deployments current and benefit from performance improvements. - Adds **Bootstrap 5** by default in Back Office. **Business benefits:** - Reduces memory usage and increases throughput for Valkey and Redis. - Reduces security and operational risks by avoiding end-of-life database versions. - Improved development–production parity, minimizing runtime incompatibilities. - Future-proofs database, PHP, and RabbitMQ support to align with vendor support timelines and enterprise requirements. **Documentation:** - [Docker SDK service configuration](/docs/dg/dev/integrate-and-configure/configure-services.html) - [System Requirements](/docs/dg/dev/system-requirements/latest/system-requirements.html) - [Upgrade Back Office to Bootstrap 5](/docs/pbc/all/back-office/latest/base-shop/install-and-upgrade/upgrade-the-back-office-to-bootstrap-5.html) ### OpenTelemetry Instrumentation Update {% include badge.html type="improvement" %} This update improves OpenTelemetry instrumentation to increase trace accuracy and compatibility across Storefront, Backend API, and GLUE applications. You benefit from resolved naming inconsistencies and improved locale handling for monitoring plugins. **Key capabilities:** - Corrected root span naming for Storefront and Backend API to ensure consistent and meaningful traces. - Fixed compatibility of `MonitoringRequestTransactionEventDispatcherPlugin` with GLUE applications by improving locale resolution logic. - Improved robustness of monitoring setup to better support multiple application contexts without relying on hard-coded application name checks. **Business benefits:** - More accurate and consistent distributed tracing across all application types. - Improved observability for GLUE-based APIs. **Documentation:** - [OpenTelemetry instrumentation](/docs/ca/dev/monitoring/spryker-monitoring-integration/opentelemetry-instrumentation.html) ### Web Profiler enhancements {% include badge.html type="improvement" %} You can now use an improved Web Profiler experience to better support performance investigations and troubleshooting during development: - Fixed an incorrect template path used by `WebProfilerExternalHttpDataCollectorPlugin`. - Added new profiling views for **Yves Ajax** and **Gateway** requests so you can more easily observe request and response flows. - Introduced **Web Profiler improvements: External HTTP Logger**, which includes: - A data collector interface to capture and inspect third-party HTTP calls. - An in-memory logger to record external requests. - Public documentation describing configuration and usage. **Key capabilities:** - Improved visibility into third-party HTTP calls to help you detect bottlenecks, N+1 patterns, and slow dependencies. - Broader profiling coverage across common Yves interaction patterns that you use in storefront development. **Business benefits:** - Faster root-cause analysis during development and quality assurance. - Reduced time spent debugging external integrations and network-related performance regressions during development and testing. **Module releases:** - [Added Yves ajax and ZedRequest profiles to WebProfiler](https://api.release.spryker.com/release-group/6222) - [Fix wrong template name in WebProfilerExternalHttpDataCollectorPlugin](https://api.release.spryker.com/release-group/6210) - [External Custom Requests visible in Web Profiler](https://api.release.spryker.com/release-group/6162) **Documentation:** - [Web Profiler Widget for Yves AJAX](/docs/dg/dev/integrate-and-configure/integrate-development-tools/integrate-web-profiler-widget-for-yves.html) - [Web Profiler for Backend Gateway](/docs/dg/dev/integrate-and-configure/integrate-development-tools/integrate-web-profiler-for-backend-gateway.html) - [WebProfiler Widget monitoring of external HTTP calls](/docs/dg/dev/guidelines/performance-guidelines/external-http-requests.html) ### Faster local development and CI builds through Composer optimization {% include badge.html type="improvement" %} This release introduces a Composer plugin for Demo Shops that splits broad PSR-4 namespaces into **layer- and module-specific** namespaces during autoload generation. This approach reduces autoload scanning overhead and improves rendering and build performance. **Key capabilities:** - Converts general `Spryker\\` namespace mappings into granular mappings, such as `Spryker\\Zed\\<Module>\\` and `Spryker\\Yves\\<Module>\\`. - Works in both development and production modes and applies consistently across Demo Shops. **Business benefits:** - Improved page rendering speed in Yves and back office during development. - Faster container and image build times in CI and cloud environments, which improves delivery throughput. **Module release:** - [Composer Autoload Plugin](https://github.com/spryker/composer-autoload-plugin/releases/tag/0.1.0) **Installation instructions:** Inside your container execute the following command, answer `yes` when asked to trust this plugin: ```bash composer require spryker/composer-autoload-plugin ``` ### Improved developer productivity and efficiency {% include badge.html type="improvement" %} **Key capabilities:** - The coding standards remove the need for docblocks that duplicate already declared type information for methods and properties, which reduces noise and maintenance overhead. - A new console helper lets you run a CLI command in a loop for extended periods, which is useful for high-load projects and operational workflows. - You can override Webpack, JavaScript, and SCSS configurations for ZED at the project level. **Business benefits:** - You spend less developer time on non-value-adding code formatting tasks. - You have less need for custom scripts to safely rerun console commands. **Module releases:** - [Adjust sniffer rules for Spryker modules to exclude docblocks from checks](https://api.release.spryker.com/release-group/6097) - [Multi-process run console](/docs/dg/dev/backend-development/cronjobs/multi-process-run-console.html) - [Overriding Webpack, JS, SCSS for ZED on the project level](/docs/dg/dev/frontend-development/latest/zed/overriding-webpack-js-scss-for-zed-on-the-project-level.html) Wed, 24 Jun 2026 08:22:15 +0000 https://docs.spryker.com/docs/about/all/releases/release-notes-202512.0.html https://docs.spryker.com/docs/about/all/releases/release-notes-202512.0.html {% include pbc/all/install-features/latest/install-the-shipment-feature.md %} <!-- To edit, see /_includes/pbc/all/install-features/202311.0/install-the-shipment-feature.md --> Wed, 24 Jun 2026 08:22:15 +0000 https://docs.spryker.com/docs/pbc/all/carrier-management/latest/base-shop/install-and-upgrade/install-features/install-the-shipment-feature.html https://docs.spryker.com/docs/pbc/all/carrier-management/latest/base-shop/install-and-upgrade/install-features/install-the-shipment-feature.html <p>The Commerce MCP Server connects AI assistants to your Spryker storefront through the <a href="https://modelcontextprotocol.io/docs/getting-started/intro">Model Context Protocol (MCP)</a>, an open standard for connecting AI applications to external systems. It turns core commerce operations — product discovery, cart management, and checkout — into a set of standardized tools that any MCP-compatible AI agent, such as Claude, ChatGPT, or Perplexity, can call directly.</p> <p>The result is <em>agentic commerce</em>: a shopper describes what they want in natural language, and the AI assistant searches the catalog, builds a cart, and completes the order using your existing Spryker Storefront API — without a person navigating the storefront manually.</p> <section class='info-block info-block--warning'><i class='info-block__icon icon-warning'></i><div class='info-block__content'><div class="info-block__title">Preview capability</div> <p>The Commerce MCP Server is an early-access preview that demonstrates how Spryker commerce can be exposed to AI agents. It is intended for demonstration, evaluation, and prototyping. For a production rollout, engage Spryker professional services.</p> </div></section> <h2 id="problems-it-solves">Problems it solves</h2> <p>Shoppers and buyers increasingly start tasks inside AI assistants rather than on a website. Traditional storefronts are built for human clicks and are not reachable by an AI agent, which creates several challenges:</p> <table> <thead> <tr> <th>CHALLENGE</th> <th>HOW THE COMMERCE MCP SERVER HELPS</th> </tr> </thead> <tbody> <tr> <td>AI assistants cannot transact against a standard storefront.</td> <td>Exposes commerce operations as MCP tools that any MCP-compatible assistant can discover and call.</td> </tr> <tr> <td>Connecting each new AI assistant requires custom, one-off API integration.</td> <td>Uses a single open protocol (MCP), so one integration works across every MCP-compatible client instead of a separate adapter per assistant.</td> </tr> <tr> <td>Catalog search, cart, and checkout each expose different APIs that an agent must learn.</td> <td>Provides a consistent, documented set of tools with input validation, so the assistant calls clear actions instead of orchestrating raw API calls.</td> </tr> <tr> <td>Building an agentic shopping experience usually means replatforming.</td> <td>Runs on top of your existing Spryker Storefront API — no changes to the underlying commerce platform.</td> </tr> </tbody> </table> <h2 id="what-the-commerce-mcp-server-covers">What the Commerce MCP Server covers</h2> <p>The server exposes the core path from discovery to order. The following commerce capabilities are available to connected AI assistants:</p> <table> <thead> <tr> <th>AREA</th> <th>CAPABILITIES</th> </tr> </thead> <tbody> <tr> <td>Product discovery</td> <td>Natural-language catalog search with filtering by facets (for example, brand or price range), sorting, and pagination. Retrieval of detailed product information by SKU.</td> </tr> <tr> <td>Shopping cart</td> <td>Add items to a cart, view cart contents and totals, update item quantities, and remove items. Supported for both guest and authenticated shoppers.</td> </tr> <tr> <td>Checkout</td> <td>Retrieve available payment methods, shipment methods, and addresses, then place an order with customer, billing, shipping, payment, and shipment details. Supported for both guest and authenticated shoppers.</td> </tr> <tr> <td>Orders</td> <td>Retrieve order details and order history for authenticated customers.</td> </tr> <tr> <td>Customer access</td> <td>Authenticate a customer to obtain an access token, or start an anonymous guest session for shopping without an account.</td> </tr> </tbody> </table> <p>In addition to these actions, the server ships with built-in guidance for common scenarios — product search, cart management, customer service, order fulfillment, and product recommendations — that help the AI assistant choose and combine the right operations for a shopper’s request.</p> <h2 id="current-scope">Current scope</h2> <p>As a preview, the server focuses on the most common storefront journey. Be aware of the following boundaries when evaluating it:</p> <ul> <li><strong>Simple products.</strong> The flow targets standard catalog products added by their SKU. Configurable products, bundles, gift cards, and complex product-option selection are not specifically handled.</li> <li><strong>Demonstration payment.</strong> Checkout defaults to a demonstration payment method (invoice). Integration with a live payment service provider is outside the preview scope.</li> <li><strong>Order history for authenticated customers.</strong> Retrieving past orders requires an authenticated customer session.</li> <li><strong>Core journey only.</strong> Capabilities such as promotions and vouchers, wishlists, returns, and marketplace or merchant operations are not part of the current preview.</li> </ul> <h2 id="who-benefits">Who benefits</h2> <table> <thead> <tr> <th>ROLE</th> <th>BENEFIT</th> </tr> </thead> <tbody> <tr> <td>Shoppers and B2B buyers</td> <td>Search, build a cart, and complete an order through a conversational AI assistant, without navigating the storefront manually.</td> </tr> <tr> <td>Merchants and business teams</td> <td>Reach customers on emerging AI-driven channels and offer guided, conversational buying experiences on top of the existing catalog and checkout.</td> </tr> <tr> <td>Developers and integrators</td> <td>Connect AI assistants through one open protocol instead of building a custom integration per assistant, reusing the existing Spryker Storefront API.</td> </tr> </tbody> </table> <h2 id="developer-resources">Developer resources</h2> <table> <thead> <tr> <th>RESOURCE</th> <th>DESCRIPTION</th> </tr> </thead> <tbody> <tr> <td><a href="/docs/dg/dev/ai/ai-commerce/commerce-mcp-server/commerce-mcp-server.html">Commerce MCP Server</a></td> <td>Technical overview: architecture, transports, available tools and prompts, and configuration.</td> </tr> </tbody> </table> Mon, 22 Jun 2026 15:46:12 +0000 https://docs.spryker.com/docs/pbc/all/ai-commerce/latest/commerce-mcp-server.html https://docs.spryker.com/docs/pbc/all/ai-commerce/latest/commerce-mcp-server.html <p>The Commerce MCP Server is a standalone <a href="https://modelcontextprotocol.io/docs/getting-started/intro">Model Context Protocol (MCP)</a> server that exposes Spryker storefront operations as MCP tools and prompts. It enables AI assistants to search the catalog, manage carts, and complete checkout by calling the Spryker Storefront API on the shopper’s behalf.</p> <p>For the business overview, use cases, and capability scope, see <a href="/docs/pbc/all/ai-commerce/latest/commerce-mcp-server.html">Commerce MCP Server</a>.</p> <section class='info-block info-block--warning'><i class='info-block__icon icon-warning'></i><div class='info-block__content'><div class="info-block__title">Preview capability</div> <p>This is an early-access preview intended for demonstration, evaluation, and prototyping. It uses simplified security and error handling and is not hardened for production. For production implementations, engage Spryker professional services.</p> </div></section> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Related MCP server</div> <p>The Commerce MCP Server connects AI assistants to the <em>storefront</em> (the Storefront API). It is distinct from the <a href="/docs/dg/dev/ai/ai-dev/ai-dev-mcp-server.html">AI Dev MCP Server</a>, which exposes <em>developer</em> tooling such as transfer structures and OMS transitions to AI assistants working on a Spryker project.</p> </div></section> <h2 id="architecture">Architecture</h2> <p>The server sits between an MCP client and the Spryker Storefront API. A request flows through the following layers:</p> <div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>AI assistant (MCP client) -&gt; transport (stdio | HTTP | SSE) -&gt; tool and prompt registries -&gt; Spryker API service -&gt; Spryker Storefront API </code></pre></div></div> <ul> <li><strong>Transports.</strong> The server supports three transports, selectable at startup: <code>stdio</code> for desktop and CLI MCP clients, <code>HTTP</code> for request and response integrations, and <code>SSE</code> (Server-Sent Events) for real-time web applications.</li> <li><strong>Tools and prompts.</strong> Each commerce operation is implemented as a tool with a validated input schema. Prompts provide context-aware guidance that helps the assistant choose and combine tools.</li> <li><strong>Spryker API service.</strong> A central HTTP client handles communication with the Storefront API, including request timeouts, retries with exponential backoff, and structured error responses. Client errors (4xx) are not retried.</li> <li><strong>Authentication.</strong> Tools accept a token. An authenticated customer token is sent as a bearer token, while a guest session token is sent as an anonymous customer identifier. This lets the same cart and checkout tools serve both authenticated and guest shoppers.</li> </ul> <h2 id="available-tools">Available tools</h2> <p>The server provides the following tools for storefront operations.</p> <h3 id="product-discovery">Product discovery</h3> <table> <thead> <tr> <th>TOOL</th> <th>DESCRIPTION</th> </tr> </thead> <tbody> <tr> <td><code>product-search</code></td> <td>Searches the product catalog. Supports a query string, value facets (for example, brand), range facets (for example, price), sorting, and pagination.</td> </tr> <tr> <td><code>get-product</code></td> <td>Retrieves detailed information for a product by its abstract SKU.</td> </tr> </tbody> </table> <h3 id="customer-access">Customer access</h3> <table> <thead> <tr> <th>TOOL</th> <th>DESCRIPTION</th> </tr> </thead> <tbody> <tr> <td><code>authenticate</code></td> <td>Authenticates a customer with a username and password to obtain an access token. If no credentials are provided, it creates an anonymous guest session token.</td> </tr> </tbody> </table> <h3 id="shopping-cart">Shopping cart</h3> <table> <thead> <tr> <th>TOOL</th> <th>DESCRIPTION</th> </tr> </thead> <tbody> <tr> <td><code>add-to-cart</code></td> <td>Adds a product to an authenticated customer’s cart by concrete SKU. Creates a cart if none exists.</td> </tr> <tr> <td><code>guest-add-to-cart</code></td> <td>Adds a product to a guest shopper’s cart by concrete SKU.</td> </tr> <tr> <td><code>get-cart</code></td> <td>Retrieves cart contents and totals for an authenticated or guest shopper.</td> </tr> <tr> <td><code>update-cart-item</code></td> <td>Updates the quantity of an item in a cart.</td> </tr> <tr> <td><code>remove-from-cart</code></td> <td>Removes an item from a cart.</td> </tr> </tbody> </table> <h3 id="checkout-and-orders">Checkout and orders</h3> <table> <thead> <tr> <th>TOOL</th> <th>DESCRIPTION</th> </tr> </thead> <tbody> <tr> <td><code>get-checkout-data</code></td> <td>Retrieves available payment methods, shipment methods, and addresses for a cart.</td> </tr> <tr> <td><code>checkout</code></td> <td>Places an order from a cart using customer data, billing and shipping addresses, a payment method, and a shipment method.</td> </tr> <tr> <td><code>get-order</code></td> <td>Retrieves order details and history for an authenticated customer. Returns a specific order when an order reference is provided, or all orders otherwise.</td> </tr> </tbody> </table> <h2 id="available-prompts">Available prompts</h2> <p>The server includes prompts that guide AI assistants through common scenarios. Each prompt explains which tools to use and how to combine them.</p> <table> <thead> <tr> <th>PROMPT</th> <th>DESCRIPTION</th> </tr> </thead> <tbody> <tr> <td><code>product-search</code></td> <td>Guides product discovery and search, including category, price range, and brand filtering.</td> </tr> <tr> <td><code>cart-management</code></td> <td>Assists with adding, removing, viewing, and updating cart items, and with checkout guidance.</td> </tr> <tr> <td><code>customer-service</code></td> <td>Supports authentication, order status, and account inquiries.</td> </tr> <tr> <td><code>order-fulfillment</code></td> <td>Guides the full flow from cart to completed order.</td> </tr> <tr> <td><code>product-recommendations</code></td> <td>Generates recommendations based on stated preferences and context.</td> </tr> </tbody> </table> <h2 id="configuration">Configuration</h2> <p>The server is configured through environment variables, which are validated at startup. The key settings are:</p> <table> <thead> <tr> <th>VARIABLE</th> <th>DESCRIPTION</th> </tr> </thead> <tbody> <tr> <td><code>SPRYKER_API_BASE_URL</code></td> <td>Base URL of the Spryker Storefront API the server connects to.</td> </tr> <tr> <td><code>SPRYKER_API_TIMEOUT</code></td> <td>Request timeout in milliseconds.</td> </tr> <tr> <td><code>SPRYKER_API_RETRY_ATTEMPTS</code></td> <td>Number of retry attempts for failed requests.</td> </tr> <tr> <td><code>SPRYKER_API_RETRY_DELAY</code></td> <td>Base delay between retries in milliseconds, used for exponential backoff.</td> </tr> <tr> <td><code>MCP_TRANSPORT</code></td> <td>Transport type: <code>stdio</code>, <code>http</code>, or <code>sse</code>.</td> </tr> <tr> <td><code>MCP_HTTP_PORT</code>, <code>MCP_HTTP_HOST</code>, <code>MCP_HTTP_ENDPOINT</code></td> <td>Network settings for the HTTP and SSE transports.</td> </tr> <tr> <td><code>LOG_LEVEL</code></td> <td>Logging verbosity. The level can also be changed at runtime through the MCP <code>logging/setLevel</code> request.</td> </tr> </tbody> </table> <h2 id="connect-an-ai-client">Connect an AI client</h2> <p>Most desktop and CLI AI assistants connect over the <code>stdio</code> transport. You register the server as an MCP server in the client’s configuration, providing the command to start it and the <code>SPRYKER_API_BASE_URL</code> of your Storefront API.</p> <p>For example, in a Claude Desktop <code>claude_desktop_config.json</code>:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nl">"mcpServers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"spryker-commerce"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"command"</span><span class="p">:</span><span class="w"> </span><span class="s2">"npx"</span><span class="p">,</span><span class="w"> </span><span class="nl">"args"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"spryker-mcp-server"</span><span class="p">],</span><span class="w"> </span><span class="nl">"env"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"SPRYKER_API_BASE_URL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://your-storefront-api.com"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre></div></div> <p>After saving the configuration, restart the AI client. The assistant then discovers the available tools and prompts automatically and can start handling commerce requests. Web applications can instead connect over the <code>HTTP</code> or <code>SSE</code> transport by pointing the client at the configured host, port, and endpoint.</p> <h2 id="compatibility">Compatibility</h2> <p>The server is compatible with the Spryker Commerce OS Storefront API. It uses bearer-token authentication for registered customers and an anonymous customer identifier for guest sessions, and it expects responses in the JSON:API format.</p> Mon, 22 Jun 2026 15:02:34 +0000 https://docs.spryker.com/docs/dg/dev/ai/ai-commerce/commerce-mcp-server/commerce-mcp-server.html https://docs.spryker.com/docs/dg/dev/ai/ai-commerce/commerce-mcp-server/commerce-mcp-server.html