Spryker Documentation

Resource Schemas

Tue, 05 May 2026 07:54:35 +0000

This document explains how to define API Platform resource schemas in Spryker. ## Schema file structure API Platform uses YAML files to define resource schemas. Resource schemas describe the structure, operations, and behavior of your API resources. ### Schema location Resource schemas must be placed in the `resources/api/{api-type}/` directory within your module: ```MARKDOWN src/ ├── Spryker/ │ └── {Module}/ │ └── resources/ │ └── api/ │ ├── storefront/ │ │ └── resource-name.resource.yml │ └── backend/ │ └── resource-name.resource.yml ├── SprykerFeature/ │ └── {Feature}/ │ └── resources/ │ └── api/ │ └── backend/ │ └── resource-name.resource.yml └── Pyz/ └── Glue/ └── {Module}/ └── resources/ └── api/ └── backend/ └── resource-name.resource.yml ``` ## CodeBucket resources API Platform supports CodeBucket-specific resource variants that are resolved at runtime based on the `APPLICATION_CODE_BUCKET` environment constant. This enables Code Bucket-specific API resources without requiring separate container compilations. ### CodeBucket schema file naming Resource schemas follow the pattern: `{resource-name}.resource.yml` Validation schemas follow the pattern: `{resource-name}.validation.yml` CodeBuckets are specified inside the schema files, not in the filename. ```MARKDOWN src/Pyz/Glue/Store/resources/api/backend/ ├── stores.resource.yml # Resource schema (CodeBucket variants defined inside) └── stores.validation.yml # Validation schema (CodeBucket variants defined inside) ``` ### Generated class naming The generator creates classes following the pattern: `{ResourceName}{CodeBucket}{ApiType}Resource` | Schema File | CodeBucket (defined in file) | Generated Class | CODE_BUCKET Constant | |-------------|------------------------------|----------------|---------------------| | `stores.resource.yml` | None (base) | `StoresBackendResource` | Not present (base resource) | | `stores.resource.yml` | EU | `StoresEUBackendResource` | `'EU'` | | `stores.resource.yml` | AT | `StoresATBackendResource` | `'AT'` | ### How CodeBucket resolution works 1. **Schema definition**: Define CodeBucket variants inside schema files using `codeBucket: EU` 2. **Constant generation**: Generator adds `public const string CODE_BUCKET = 'EU';` to variant classes 3. **Runtime resolution**: System reads `APPLICATION_CODE_BUCKET` and selects matching resource class 4. **Graceful fallback**: If no matching variant exists, base resource is used ### URL consistency All CodeBucket variants share the same URL path, with the Code Bucket defined in the domain: - EU variant: `glue-backend.eu.spryker.local/stores` → `StoresEUBackendResource` - AT variant: `glue-backend.at.spryker.local/stores` → `StoresATBackendResource` - DE variant: `glue-backend.de.spryker.local/stores` → `StoresBackendResource` (or `StoresDEBackendResource` if variant exists) The URL path is identical (`/stores`), but the Code Bucket in the domain determines which resource variant is used. Only properties, validations, and business logic differ between variants. ### When to use CodeBucket resources Use CodeBucket variants when you need: - Code Bucket-specific properties (EU GDPR fields, tax rates) - Code Bucket-specific validation rules - Country-specific business logic - Feature variations per Code Bucket For a comprehensive guide including implementation examples, see [CodeBucket Support](/docs/dg/dev/architecture/api-platform/code-buckets.html). ## Resource schema syntax ### Minimal example ```yaml resource: name: Products shortName: Product description: "Product resource" operations: - type: Get - type: GetCollection properties: id: type: integer writable: false identifier: true name: type: string ``` ### Complete example with all options ```yaml # yaml-language-server: $schema=../../../../SprykerSdk/Api/resources/schemas/api-resource-schema-v1.json resource: # Resource identification name: Customers # Internal name (used for schema merging) shortName: Customer # URL name (becomes /customers) description: "Customer resource" # OpenAPI description # State providers and processors provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" processor: "Pyz\\Glue\\Customer\\Api\\Backend\\Processor\\CustomerBackendProcessor" # Pagination configuration paginationEnabled: true paginationItemsPerPage: 10 paginationMaximumItemsPerPage: 100 paginationClientEnabled: true paginationClientItemsPerPage: true # Security security: "is_granted('ROLE_ADMIN')" securityPostDenormalize: "is_granted('EDIT', object)" # Operations operations: - type: Post # Create new resource - type: Get # Get single resource - type: GetCollection # Get collection with pagination - type: Put # Replace entire resource - type: Patch # Update partial resource - type: Delete # Delete resource # Properties properties: idCustomer: type: integer description: "The unique identifier of the customer." writable: false # Read-only property readable: true # Include in responses (default: true) email: type: string description: "The email address." required: true # Required for all operations openapiContext: example: "john@example.com" format: "email" firstName: type: string description: "First name." openapiContext: example: "John" minLength: 1 maxLength: 100 status: type: string description: "Customer status." openapiContext: example: "active" schema: enum: ["active", "inactive", "pending"] customerReference: type: string description: "Unique customer reference." writable: false identifier: true # Use as URL identifier instead of @id dateOfBirth: type: string description: "Date of birth." openapiContext: format: "date" example: "1990-01-01" isActive: type: boolean description: "Active status." default: true creditLimit: type: number description: "Credit limit." openapiContext: format: "float" example: 5000.00 ``` ## Property types ### Supported types | Type | PHP Type | Example | Description | |------|----------|---------|-------------| | `string` | `string` | `"John"` | Text values | | `integer` | `int` | `42` | Whole numbers | | `number` | `float` | `3.14` | Decimal numbers | | `boolean` | `bool` | `true` | True/false values | | `array` | `array` | `["a", "b"]` | Lists of values | | `object` | `object` | `{"key": "value"}` | Strictly typed nested objects | | `map` | `array` | `{"key": "value"}` | Free-shape associative payloads documented via `openapiContext`. Stored as PHP `array` and rendered as `type: object` in the OpenAPI specification. | | `mixed` | `mixed` | any | Use only when the payload genuinely has no fixed shape and cannot be described via `openapiContext`. | Use `map` when the payload is a structured JSON object whose schema you want to describe via `openapiContext` rather than a strongly typed PHP class. This is the recommended type whenever a request or response body is a JSON object with a known shape but no dedicated DTO class — it keeps the property typed as a simple `array` in PHP while still producing rich OpenAPI metadata and a working "Try Out" body in Swagger UI. See [Documenting nested properties for OpenAPI and Swagger UI](#documenting-nested-properties-for-openapi-and-swagger-ui) for the full pattern. ### Property attributes #### writable Controls if property can be sent in requests (POST/PUT/PATCH): ```yaml password: type: string writable: true # Can be sent in requests readable: false # Not included in responses ``` #### readable Controls if property is included in responses: ```yaml idCustomer: type: integer writable: false # Cannot be modified readable: true # Included in responses ``` #### identifier Marks property as URL identifier: ```yaml customerReference: type: string identifier: true # URL becomes /customers/{customerReference} ``` #### required Makes property mandatory (use validation schemas for detailed rules): ```yaml email: type: string required: true # Must be present ``` #### default Sets default value: ```yaml isActive: type: boolean default: true # Defaults to true if not provided ``` ## Documenting nested properties for OpenAPI and Swagger UI Many endpoints accept or return structured JSON payloads — for example, a payment initialization request that takes `payment`, `quote`, and `customer` sub-objects. Without explicit metadata, those payloads appear as opaque `object` entries in the OpenAPI document, which means: - The generated OpenAPI specification does not describe the child fields, their types, or which ones are required. - The Swagger UI "Try Out" button shows an empty request body, forcing consumers to read code or external documentation to discover the expected shape. The `map` property type combined with nested `openapiContext` entries closes both gaps. ### When to use this pattern Use this pattern when the request or response body is a structured JSON object whose schema you want to publish through OpenAPI, but you do not want to introduce a dedicated typed PHP class for it. Typical cases are: - Request payloads that aggregate fields from multiple transfer objects (for example, payment selection plus quote context). - PSP- or provider-specific response payloads whose shape varies by configuration. For payloads with a stable, strongly typed shape, prefer `type: object` so the generated PHP class enforces the structure at the language level. ### Pattern Combine `type: map` on the property with the following entries inside `openapiContext`: | Entry | Purpose | |-------|---------| | `properties` | Declares each child field with its own `type`, `description`, `format`, and `example`. Used by Swagger UI to render the field-by-field schema. | | `required` | Lists the child fields that must be present on a request. Drives the "required" markers in Swagger UI and the OpenAPI specification. | | `example` | A complete sample payload. This is the value Swagger UI prefills into the "Try Out" body, so consumers can execute the request immediately. | When the property is a `map`, the generator merges `'type' => 'object'` into the emitted `openapiContext`, so the property appears as an object — with the documented schema — in the OpenAPI document while staying as a plain PHP `array` in the generated resource class. ### Worked example The following extract is taken from `src/Spryker/PaymentsRestApi/resources/api/storefront/payments.resource.yml`. It shows three common shapes: a flat request object (`payment`), a request object with nested object children (`quote`), and a response-only object whose contents vary at runtime (`preOrderPaymentData`). ```yaml properties: payment: type: map writable: true readable: false required: true description: 'Payment selection for the pre-order initialization' openapiContext: required: ['paymentProviderName', 'paymentMethodName', 'amount'] properties: paymentProviderName: type: string example: 'DummyPayment' paymentMethodName: type: string example: 'Invoice' amount: type: integer description: 'Amount in minor units (cents)' example: 9999 example: paymentProviderName: 'DummyPayment' paymentMethodName: 'Invoice' amount: 9999 quote: type: map writable: true readable: false required: true description: 'Quote context required to initialize the payment' openapiContext: required: ['customer', 'billingAddress', 'currency'] properties: customer: type: object required: ['firstName', 'lastName', 'email'] properties: firstName: { type: string, example: 'Sonia' } lastName: { type: string, example: 'Wagner' } email: { type: string, format: email, example: 'sonia@acme.com' } billingAddress: type: object required: ['iso2Code'] properties: iso2Code: { type: string, example: 'DE' } currency: type: object required: ['code'] properties: code: { type: string, example: 'EUR' } example: customer: firstName: 'Sonia' lastName: 'Wagner' email: 'sonia@acme.com' billingAddress: iso2Code: 'DE' currency: code: 'EUR' preOrderPaymentData: type: map writable: false readable: true required: false description: 'PSP-specific response payload returned by the payment provider' openapiContext: example: transactionId: 'tx_abc123' redirectUrl: 'https://psp.example.com/pay/tx_abc123' ``` ### Read-only versus write-only payloads - **Write-only request payloads** (`writable: true`, `readable: false`) should declare `properties`, `required`, and `example`. The first two drive request validation and the generated OpenAPI schema; `example` makes the Swagger UI "Try Out" body usable without edits. - **Read-only response payloads** (`writable: false`, `readable: true`) only need `openapiContext.example` when the response shape is dynamic. If the response shape is fixed, prefer declaring `properties` (and optionally `required`) so consumers see the full schema. ### Validation note `openapiContext.required` controls only the OpenAPI documentation. If a request field must be enforced at runtime, add the matching constraint to the resource's validation schema — see [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html). ## Operations Define which HTTP operations are available for the resource: ```yaml operations: - type: Get # GET /customers/{id} - type: GetCollection # GET /customers - type: Post # POST /customers - type: Put # PUT /customers/{id} - type: Patch # PATCH /customers/{id} - type: Delete # DELETE /customers/{id} ``` The operation names map to HTTP methods: - `post` → POST (create) - `get` → GET (single resource) - `getCollection` → GET (collection) - `put` → PUT (replace) - `patch` → PATCH (update) - `delete` → DELETE (remove) ## Pagination API Platform provides built-in pagination for collection endpoints (`GetCollection`). You can configure pagination behavior per resource using YAML schema options. ### Pagination options | Option | Type | Description | |--------|------|-------------| | `paginationEnabled` | `boolean` | Enables or disables pagination for this resource. When `false`, `GetCollection` returns all results without pagination. Default: inherits from global configuration. | | `paginationItemsPerPage` | `integer` | Number of items returned per page. Overrides the global default. | | `paginationMaximumItemsPerPage` | `integer` | Maximum number of items a client can request per page via `itemsPerPage` query parameter. Prevents clients from requesting excessively large pages. | | `paginationClientEnabled` | `boolean` | Allows clients to enable or disable pagination via the `pagination` query parameter (for example, `?pagination=false`). | | `paginationClientItemsPerPage` | `boolean` | Allows clients to set the number of items per page via the `itemsPerPage` query parameter (for example, `?itemsPerPage=50`). | The global default for `paginationItemsPerPage` is defined in the project's `api_platform.php` configuration file. To override it for a specific resource, set `paginationItemsPerPage` in the resource schema. ### Minimal pagination example ```yaml resource: name: Products shortName: products paginationEnabled: true paginationItemsPerPage: 10 operations: - type: GetCollection ``` ### Full pagination example ```yaml resource: name: Products shortName: products paginationEnabled: true paginationItemsPerPage: 20 paginationMaximumItemsPerPage: 100 paginationClientEnabled: true paginationClientItemsPerPage: true operations: - type: GetCollection - type: Get ``` With this configuration, clients can use the following query parameters: ```bash # Default pagination (20 items per page) GET /products # Navigate to page 3 GET /products?page=3 # Request 50 items per page (up to maximum of 100) GET /products?itemsPerPage=50 # Disable pagination to get all results GET /products?pagination=false ``` ### Generated output The pagination options are rendered as named parameters in the `#[ApiResource]` attribute: ```php #[ApiResource( operations: [new GetCollection(), new Get()], shortName: 'products', provider: ProductsBackendProvider::class, paginationItemsPerPage: 20, paginationEnabled: true, paginationMaximumItemsPerPage: 100, paginationClientEnabled: true, paginationClientItemsPerPage: true )] ``` ### Provider requirements For pagination to work, your Provider must return a `TraversablePaginator` instance for collection operations: ```php use ApiPlatform\State\Pagination\TraversablePaginator; return new TraversablePaginator( new \ArrayObject($resources), $currentPage, $itemsPerPage, $totalItems ); ``` If `paginationEnabled` is `true` but the Provider returns a plain array, API Platform wraps the result in a `PartialPaginatorInterface`, which may not include total count or page metadata. ### Global pagination defaults Global pagination defaults can be configured in the application configuration file. Per-resource settings override the global defaults. See [API Platform Configuration](/docs/dg/dev/architecture/api-platform/configuration.html) for details. ## Relationships Define relationships between resources to enable including related resources via the `?include=` query parameter. ### includes section Declares what relationships this resource can include: ```yaml includes: - relationshipName: addresses targetResource: CustomersAddresses uriVariableMappings: customerReference: customerReference ``` **Properties:** - `relationshipName`: Name used in `?include=` parameter - `targetResource`: Name of the resource to include - `uriVariableMappings`: Maps properties from parent to child provider ### includableIn section Declares where this resource can be included: ```yaml includableIn: - resource: Customers relationshipName: addresses uriVariableMappings: customerReference: customerReference ``` Both declarations must match for validation to pass. For detailed information about relationships, see [Relationships](/docs/dg/dev/architecture/api-platform/relationships.html). ## Resource generation process ### Generation workflow The resource generation process is organized into distinct phases, each producing result objects for comprehensive error tracking and reporting: ```MARKDOWN 1. Preparation Phase ↓ 2. Schema Parsing Phase → ParseResult - Load validation schemas - Parse validation rules - Load resource schemas - Parse resource definitions ↓ 3. Schema Merging Phase → MergeResult - Merge schemas (Core → Feature → Project) - Track contributing source files ↓ 4. Validation Phase → ValidationResult - Validate merged schemas - Apply validation rules ↓ 5. Code Generation Phase - Generate PHP resource classes - Write files to output directory ↓ 6. Cache Update ``` ### Result objects Each phase produces result objects that encapsulate both successful outcomes and failures: - **ParseResult**: Contains grouped schemas and tracks failed validation files and schema files that could not be parsed - **MergeResult**: Contains successfully merged schemas and tracks resources that failed to merge - **ValidationResult**: Contains validated schemas and tracks resources that failed validation with detailed error messages This structured approach ensures that errors in one resource do not block the generation of other valid resources, and provides clear feedback about what succeeded and what failed. ### Multi-layer schema merging Spryker automatically merges schemas from multiple layers: **Core layer** (lowest priority): **vendor/spryker/customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: type: string firstName: type: string ``` **Feature layer** (medium priority): **src/SprykerFeature/CRM/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: phone: type: string # Added property ``` **Project layer** (highest priority): **src/Pyz/Glue/Customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: required: true # Override core definition customField: type: string # Project-specific field ``` **Merged result:** ```yaml resource: name: Customers properties: email: type: string required: true # From project layer firstName: type: string # From core layer phone: type: string # From feature layer customField: type: string # From project layer ``` ### Generated resource class The generator creates a complete PHP class with API Platform attributes: ```php 'john@example.com'])] #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] public ?string $email = null; #[ApiProperty(identifier: true, writable: false)] public ?string $customerReference = null; public ?bool $isActive = true; // Getters, setters, toArray(), fromArray() methods... } ``` ## Debugging schemas ### Debug commands ```bash # List all resources docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug --list # Show specific resource docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug customers --api-type=backend # Show merged schema docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug customers --api-type=backend --show-merged # Show contributing source files docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug customers --api-type=backend --show-sources # Validate schemas without generating docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only ``` ### Common schema errors The generator validates schemas and provides detailed error messages: ```bash # Missing required fields Error: Resource "customers" is missing required field "name" # Invalid operation type Error: Invalid operation type "INVALID". Must be one of: Get, Post, Put, Patch, Delete, GetCollection # Invalid property type Error: Property "age" has invalid type "int". Must be one of: string, integer, number, boolean, array, object # Provider class not found Error: Provider class "Pyz\Glue\Customer\Api\Backend\Provider\MissingProvider" does not exist ``` ## Advanced schema features ### Custom URL paths Operations support `uriTemplate` and `uriVariables` to define custom URL paths, including sub-resource URLs like `/customers/{customerReference}/addresses`. #### Sub-resource with full CRUD Define a child resource with nested URLs by adding `uriTemplate` and `uriVariables` to each operation: **customers-addresses.resource.yml** ```yaml resource: name: CustomersAddresses shortName: customers-addresses operations: - type: GetCollection uriTemplate: '/customers/{customerReference}/addresses' uriVariables: customerReference: toProperty: 'customer' fromClass: CustomersStorefrontResource - type: Get uriTemplate: '/customers/{customerReference}/addresses/{uuid}' uriVariables: customerReference: toProperty: 'customer' fromClass: CustomersStorefrontResource uuid: fromClass: CustomersAddressesStorefrontResource - type: Post uriTemplate: '/customers/{customerReference}/addresses' uriVariables: customerReference: toProperty: 'customer' fromClass: CustomersStorefrontResource ``` **`uriVariables` properties:** - `fromClass`: The generated resource class the variable originates from - `toProperty`: The property on the current resource that links to the parent resource #### Action-style sub-resource For single-action endpoints nested under a parent resource: **customers-confirm-registration.resource.yml** ```yaml resource: name: CustomersConfirmRegistration shortName: customers-confirm-registration operations: - type: Post uriTemplate: /customers/{customerReference}/confirm-registration ``` For more details on `uriTemplate`, `uriVariables`, and sub-resource patterns, see the [API Platform sub-resources documentation](https://api-platform.com/docs/core/subresources/). ### Security expressions Security expressions protect resources and operations using [Symfony's ExpressionLanguage](https://symfony.com/doc/current/security/expressions.html). They require the SecurityBundle to be configured. See [How to integrate API Platform Security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) for setup instructions. {% info_block infoBox "Where roles come from" %} Roles like `ROLE_CUSTOMER` in security expressions come from OAuth scopes that are automatically mapped to Symfony roles. The mapping convention is as follows: a scope name is uppercased and prefixed with `ROLE_`. For example, the `customer` scope becomes `ROLE_CUSTOMER`. Scopes are provided by scope provider plugins registered in `OauthDependencyProvider::getScopeProviderPlugins()`. The following table lists the out-of-the-box scope provider plugins and the scopes they provide: | Plugin | Scopes | |--------|--------| | `CustomerOauthScopeProviderPlugin` | `customer` | | `CompanyUserOauthScopeProviderPlugin` | `company_user` | | `AgentOauthScopeProviderPlugin` | `agent` | | `CustomerImpersonationOauthScopeProviderPlugin` | `customer_impersonation`, `customer` | | `UserOauthScopeProviderPlugin` | `user`, plus UserType sub-plugins | | `WarehouseOauthScopeProviderPlugin` | `warehouse` | For details on how the mapping works, see [Security — Roles and OAuth scope mapping](/docs/dg/dev/architecture/api-platform/security.html). For instructions on setting up scopes, see [Integrate the authorization scopes](/docs/integrations/spryker-glue-api/backend-api/integrate-backend-api/integrate-the-authorization-scopes.html). {% endinfo_block %} Three types of security expressions are supported: | Expression | Evaluated | Use case | When to use | |-----------|-----------|----------|-------------| | `security` | Before the request is processed | Check user roles or authentication status | For role or authentication checks that do not depend on the request body. | | `securityPostDenormalize` | After the request body is deserialized | Check authorization based on submitted data | When authorization depends on the deserialized resource `object`, for example, to verify the user owns the resource being modified. | | `securityPostValidation` | After validation passes | Check authorization based on validated data | When authorization depends on validated data, for example, to verify a value is within the user's authorized limit after validation confirms the data is structurally correct. | #### Resource-level security Applies to all operations on the resource: ```yaml resource: name: Customers shortName: customers security: "is_granted('ROLE_USER')" ``` #### Operation-level security Applies to a specific operation, overriding resource-level security: ```yaml resource: name: Customers shortName: customers operations: - type: Post # No security — public registration - type: Get security: "is_granted('ROLE_USER')" - type: Patch security: "is_granted('ROLE_USER')" ``` #### Post-denormalize security Evaluated after the request body has been deserialized. The `object` variable contains the resource instance: ```yaml resource: name: Orders shortName: orders security: "is_granted('ROLE_USER')" securityPostDenormalize: "is_granted('EDIT', object)" ``` {% info_block infoBox "Custom voter attributes" %} `EDIT` in the example is a **custom voter attribute** — it is an application-defined string, not a built-in Symfony or Spryker constant. For `is_granted('EDIT', object)` to work, you must register a custom Symfony [Voter](https://symfony.com/doc/current/security/voters.html) that supports the `EDIT` attribute and implements the authorization logic, for example, checking that the authenticated user owns the resource. Use `securityPostDenormalize` when the authorization decision depends on the **submitted request data** (the deserialized `object`), such as verifying resource ownership. {% endinfo_block %} #### Post-validation security Evaluated after validation has passed: ```yaml resource: name: Payments shortName: payments securityPostValidation: "is_granted('PROCESS', object)" ``` {% info_block infoBox "Custom voter attributes" %} `PROCESS` in the example is a **custom voter attribute** — it is an application-defined string, not a built-in Symfony or Spryker constant. For `is_granted('PROCESS', object)` to work, you must register a custom Symfony [Voter](https://symfony.com/doc/current/security/voters.html) that supports the `PROCESS` attribute. Use `securityPostValidation` when the authorization decision depends on **validated data**, for example, to verify a payment amount is within the user's authorized limit after validation confirms the data is structurally correct. {% endinfo_block %} For detailed information about the authentication flow, role mapping, and accessing the authenticated user in providers, see [Security](/docs/dg/dev/architecture/api-platform/security.html). ## Generation commands ### Basic generation ```bash # Generate all configured API types docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate # Generate specific API type docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate backend docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue api:generate storefront # Generate with options docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --dry-run # Preview without writing docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only # Only validate schemas docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --resource=customers # Generate single resource ``` ### Output ```bash Generating API resources for ApiType: backend Discovering schema files... Validating schemas... OK Merging schemas... OK Generating resources: 10/10 [============================] 100% Generated: 10 file(s) Cache updated Done! ``` ## Schema validation rules The generator enforces these rules: ### Required fields Every resource must have: - `name` - Internal resource name - `shortName` - URL-friendly name - At least one `operation` - At least one `property` ### Valid operation types Only these operation types are allowed: - `Get` - Retrieve single resource - `GetCollection` - Retrieve collection - `Post` - Create resource - `Put` - Replace entire resource - `Patch` - Update partial resource - `Delete` - Delete resource ### Valid property types Only these property types are allowed: - `string` - `integer` - `number` - `boolean` - `array` - `object` - `map` - `mixed` ### Provider/Processor validation - Provider/Processor classes must exist - Classes must implement correct interfaces - Namespaces must be valid PHP namespaces ## Best practices ### 1. Use semantic naming ```yaml # ✅ Good resource: name: Customers shortName: Customer # ❌ Bad resource: name: CustomerData shortName: cust ``` ### 2. Document all properties ```yaml # ✅ Good email: type: string description: "The customer's email address used for login and notifications" # ❌ Bad email: type: string ``` ### 3. Leverage schema merging Core — define base properties: **src/Spryker/Customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: type: string ``` Project — only override what is needed: **src/Pyz/Glue/Customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: required: true # ← Only the difference ``` ### 4. Use readable/writable correctly ```yaml # Read-only fields (IDs, timestamps) idCustomer: type: integer writable: false # Write-only fields (passwords) password: type: string readable: false # Read-write fields (normal data) email: type: string writable: true readable: true ``` ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Architecture overview - [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html) - Define validation rules - [CodeBucket Support](/docs/dg/dev/architecture/api-platform/code-buckets.html) - Code Bucket-specific resources - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating resources - [API Platform Testing](/docs/dg/dev/architecture/api-platform/testing.html) - Writing and running tests - [Troubleshooting](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues - [API Platform Documentation](https://api-platform.com/docs/) - Official API Platform docs

Migration status - Glue API to API Platform

Tue, 05 May 2026 07:29:46 +0000

This document tracks Spryker's migration of API-providing modules to the **API Platform** (built on Symfony and the API Platform library). Use it to plan upgrades and check the current status of every module. {% info_block infoBox "Looking for the integration guide?" %} This page does **not** describe how to integrate API Platform into your project. For step-by-step integration instructions, see: - [Migrate to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html) - [Integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - [Integrate API Platform security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) - [API Platform architecture](/docs/dg/dev/architecture/api-platform.html) {% endinfo_block %} ## Why Spryker is moving to API Platform API Platform replaces Spryker-specific patterns for routing, authentication, and resource definition with industry-standard Symfony conventions, automatic OpenAPI schema generation, and a clean separation between resource schema, provider, and validation. | Aspect | Previous infrastructure | API Platform | |---|---|---| | Bootstrap | Spryker-specific application bootstrap | Symfony Kernel-based routing | | Resource registration | Manual plugin registration in `GlueApplicationDependencyProvider` | Declarative YAML resource definitions (`*.resource.yml`) | | Authentication | Custom flows per module | Standard OAuth2 / Symfony Security | | Coupling | Tight coupling between resource and routing logic | Clean separation: provider + resource schema + validation | | Testability | Complex to test and extend | Symfony-native, testable with standard PHPUnit patterns | | OpenAPI | Manual / partial | Automatic OpenAPI schema generation | ## General migration workflow For any module marked **Migrated**, projects upgrade in three high-level steps. Detailed instructions are in the linked integration guides above. 1. **Update the module to the API Platform-enabled version** Pull the new module version that ships the `*.resource.yml` schema and Provider class: ```bash composer update spryker/ ``` 2. **Remove the previous resource plugins** In your project's `GlueApplicationDependencyProvider`, remove the previous plugin registrations for the migrated module - typically a `ResourceRoutePlugin` (and any related `ResourceRelationshipPlugin` / expander plugins) registered in `getResourceRoutePlugins()`. For **extension-only** modules, remove or replace the corresponding plugin wiring in the parent module's dependency provider as indicated in the module's release notes. 3. **Clear caches and verify** ```bash vendor/bin/glue cache:clear vendor/bin/glue api:generate ``` Confirm the endpoint is served by API Platform by hitting it against your local Glue host - the response is now produced by the new Symfony-based stack. {% info_block infoBox "Parallel operation" %} The previous API stack and API Platform run **side by side** during the transition. You can migrate modules incrementally; modules that have not been migrated continue to be served by the previous stack. {% endinfo_block %} ### Status legend | Status | Meaning | |---|---| | Migrated | Module is available on API Platform and production-ready. | | Planned | Module is scheduled or queued for migration to API Platform. | ## Storefront API modules All StorefrontAPI and Extension-only StorefrontAPI modules. Migrated modules are listed first. | Module | Category | Status | Key endpoints | |---|---|---|---| | ContentProductAbstractListsRestApi | StorefrontAPI | Migrated | GET /content-product-abstract-lists/{id}
GET /content-product-abstract-lists/{id}/abstract-products | | MerchantProductOffersRestApi | StorefrontAPI | Migrated | GET /concrete-products/{id}/product-offers
GET /product-offers/{id} | | PaymentsRestApi | StorefrontAPI | Migrated | POST /payments
POST /payment-cancellations
POST /payment-customers | | ProductAvailabilitiesRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-availabilities
GET /concrete-products/{id}/concrete-product-availabilities | | ProductOfferAvailabilitiesRestApi | StorefrontAPI | Migrated | GET /product-offers/{id}/product-offer-availabilities | | ProductOfferPricesRestApi | StorefrontAPI | Migrated | GET /product-offers/{id}/product-offer-prices | | ProductPricesRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-prices
GET /concrete-products/{id}/concrete-product-prices | | ProductTaxSetsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/product-tax-sets | | ProductsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}
GET /concrete-products/{id} | | StoresApi | StorefrontAPI | Migrated | GET /stores | | AgentAuthRestApi | StorefrontAPI | Planned | POST /agent-access-tokens
POST /agent-customer-impersonation-access-tokens
GET /agent-customer-search | | AlternativeProductsRestApi | StorefrontAPI | Planned | GET /abstract-products/{id}/related-products
GET /concrete-products/{id}/abstract-alternative-products
GET /concrete-products/{id}/concrete-alternative-products | | AuthRestApi | StorefrontAPI | Planned | POST /token
POST /access-tokens
POST /refresh-tokens
DELETE /refresh-tokens/{id} | | AvailabilityNotificationsRestApi | StorefrontAPI | Planned | POST /availability-notifications
DELETE /availability-notifications/{id}
GET /my-availability-notifications
GET /customers/{id}/availability-notifications | | CartCodesRestApi | StorefrontAPI | Planned | POST /carts/{id}/cart-codes
DELETE /carts/{id}/cart-codes/{id}
POST /guest-carts/{id}/cart-codes
DELETE /guest-carts/{id}/cart-codes/{id} | | CartPermissionGroupsRestApi | StorefrontAPI | Planned | GET /cart-permission-groups
GET /cart-permission-groups/{id} | | CartReorderRestApi | StorefrontAPI | Planned | POST /cart-reorder | | CartsRestApi | StorefrontAPI | Planned | GET,POST /carts
GET,PATCH,DELETE /carts/{id}
POST /carts/{id}/items
PATCH,DELETE /carts/{id}/items/{id}
GET /guest-carts
GET,PATCH /guest-carts/{id}
POST /guest-carts/{id}/guest-cart-items
PATCH,DELETE /guest-carts/{id}/guest-cart-items/{id}
GET /customers/{id}/carts | | CatalogSearchRestApi | StorefrontAPI | Planned | GET /catalog-search
GET /catalog-search-suggestions | | CategoriesRestApi | StorefrontAPI | Planned | GET /category-trees
GET /category-nodes/{id} | | CheckoutRestApi | StorefrontAPI | Planned | POST /checkout-data
POST /checkout | | CmsPagesRestApi | StorefrontAPI | Planned | GET /cms-pages
GET /cms-pages/{id} | | CompaniesRestApi | StorefrontAPI | Planned | GET /companies
GET /companies/{id} | | CompanyBusinessUnitAddressesRestApi | StorefrontAPI | Planned | GET /company-business-unit-addresses
GET /company-business-unit-addresses/{id} | | CompanyBusinessUnitsRestApi | StorefrontAPI | Planned | GET /company-business-units
GET /company-business-units/{id} | | CompanyRolesRestApi | StorefrontAPI | Planned | GET /company-roles
GET /company-roles/{id} | | CompanyUserAuthRestApi | StorefrontAPI | Planned | POST /company-user-access-tokens | | CompanyUsersRestApi | StorefrontAPI | Planned | GET /company-users
GET /company-users/{id} | | ConfigurableBundleCartsRestApi | StorefrontAPI | Planned | POST /carts/{id}/configured-bundles
PATCH,DELETE /carts/{id}/configured-bundles/{id}
POST,PATCH,DELETE /guest-carts/{id}/guest-configured-bundles/{id} | | ConfigurableBundlesRestApi | StorefrontAPI | Planned | GET /configurable-bundle-templates
GET /configurable-bundle-templates/{id} | | ContentBannersRestApi | StorefrontAPI | Planned | GET /content-banners/{id} | | CustomerAccessRestApi | StorefrontAPI | Planned | GET /customer-access | | CustomersRestApi | StorefrontAPI | Planned | GET,POST /customers
GET,PATCH,DELETE /customers/{id}
GET,POST /customers/{id}/addresses
GET,PATCH,DELETE /customers/{id}/addresses/{id}
POST /customer-forgotten-password
PATCH /customer-restore-password/{id}
PATCH /customer-password/{id}
POST /customer-confirmation | | DiscountPromotionsRestApi | Extension-Only-StorefrontAPI | Planned | CartsRestApi, CartCodesRestApi | | DiscountsRestApi | StorefrontAPI | Planned | POST /carts/{id}/vouchers
DELETE /carts/{id}/vouchers/{id}
POST /guest-carts/{id}/vouchers
DELETE /guest-carts/{id}/vouchers/{id} | | EntityTagsRestApi | Extension-only StorefrontAPI | Planned | GlueApplication | | GiftCardsRestApi | Extension-only StorefrontAPI | Planned | GlueApplication | | MerchantCategoriesRestApi | Extension-only StorefrontAPI | Planned | MerchantsRestApi | | MerchantOpeningHoursRestApi | StorefrontAPI | Planned | GET /merchants/{id}/merchant-opening-hours | | MerchantProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductOfferWishlistRestApi | Extension-only StorefrontAPI | Planned | WishlistsRestApi | | MerchantProductShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi | | MerchantRelationshipProductListsRestApi | Extension-only StorefrontAPI | Planned | CustomersRestApi | | MerchantSalesReturnsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantShipmentsRestApi | Extension-only StorefrontAPI | Planned | ShipmentsRestApi | | MerchantsRestApi | StorefrontAPI | Planned | GET /merchants
GET /merchants/{id}
GET /merchants/{id}/merchant-addresses | | MultiCartsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi | | NavigationsRestApi | StorefrontAPI | Planned | GET /navigations/{id} | | OauthApi | StorefrontAPI | Planned | POST /token | | OmsRestApi | Extension-only StorefrontAPI | Planned | OrdersRestApi | | OrderAmendmentsRestApi | Extension-only StorefrontAPI | Planned | OrdersRestApi, CartsRestApi, CartReorderRestApi | | OrderPaymentsRestApi | StorefrontAPI | Planned | POST /order-payments | | OrdersRestApi | StorefrontAPI | Planned | GET /orders
GET /orders/{id}
GET /customers/{id}/orders | | PriceProductOfferVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductOfferPricesRestApi | | PriceProductVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductPricesRestApi | | ProductAttributesRestApi | StorefrontAPI | Planned | GET /product-management-attributes
GET /product-management-attributes/{id} | | ProductBundleCartsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, ShipmentsRestApi | | ProductBundlesRestApi | StorefrontAPI | Planned | GET /concrete-products/{id}/bundled-products | | ProductConfigurationShoppingListsRestApi | Extension-only StorefrontAPI | Planned | ShoppingListsRestApi | | ProductConfigurationWishlistsRestApi | Extension-only StorefrontAPI | Planned | WishlistsRestApi | | ProductConfigurationsPriceProductVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductConfigurationsRestApi, ProductConfigurationShoppingListsRestApi, ProductConfigurationWishlistsRestApi | | ProductConfigurationsRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi, CartsRestApi, OrdersRestApi | | ProductDiscontinuedRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi | | ProductImageSetsRestApi | StorefrontAPI | Planned | GET /abstract-products/{id}/abstract-product-image-sets
GET /concrete-products/{id}/concrete-product-image-sets | | ProductLabelsRestApi | StorefrontAPI | Planned | GET /product-labels/{id} | | ProductMeasurementUnitsRestApi | StorefrontAPI | Planned | GET /product-measurement-units/{id}
GET /concrete-products/{id}/sales-units | | ProductOfferSalesRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | ProductOfferServicePointAvailabilitiesRestApi | StorefrontAPI | Planned | POST /product-offer-service-point-availabilities | | ProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | ProductOffersRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi | | ProductOptionsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, OrdersRestApi, ProductsRestApi, QuoteRequestsRestApi | | ProductReviewsRestApi | StorefrontAPI | Planned | GET,POST /abstract-products/{id}/product-reviews
GET /abstract-products/{id}/product-reviews/{id} | | QuoteRequestAgentsRestApi | StorefrontAPI | Planned | GET,POST /agent-quote-requests
GET,PATCH /agent-quote-requests/{id}
POST /agent-quote-requests/{id}/agent-quote-request-cancel
POST /agent-quote-requests/{id}/agent-quote-request-revise
POST /agent-quote-requests/{id}/agent-quote-request-send-to-customer | | QuoteRequestsRestApi | StorefrontAPI | Planned | GET,POST /quote-requests
GET,PATCH /quote-requests/{id}
POST /quote-requests/{id}/quote-request-cancel
POST /quote-requests/{id}/quote-request-revise
POST /quote-requests/{id}/quote-request-send-to-user
POST /quote-requests/{id}/quote-request-convert-to-quote | | RelatedProductsRestApi | StorefrontAPI | Planned | GET /abstract-products/{id}/related-products | | SalesOrderThresholdsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, CheckoutRestApi | | SalesReturnsRestApi | StorefrontAPI | Planned | GET /return-reasons
GET,POST /returns
GET /returns/{id} | | SecurityBlockerRestApi | Extension-only StorefrontAPI | Planned | GlueApplication | | ServicePointCartsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi | | ServicePointsRestApi | StorefrontAPI | Planned | GET /service-points
GET /service-points/{id}
GET /service-points/{id}/service-point-addresses/{id} | | SharedCartsRestApi | StorefrontAPI | Planned | POST /carts/{id}/shared-carts
PATCH,DELETE /shared-carts/{id} | | ShipmentTypeProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Planned | ProductOfferServicePointAvailabilitiesRestApi | | ShipmentTypeServicePointsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi, ShipmentsRestApi, ShipmentTypesRestApi | | ShipmentTypesRestApi | StorefrontAPI | Planned | GET /shipment-types
GET /shipment-types/{id} | | ShipmentsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi, OrdersRestApi, QuoteRequestsRestApi | | ShoppingListsRestApi | StorefrontAPI | Planned | GET,POST /shopping-lists
GET,PATCH,DELETE /shopping-lists/{id}
POST /shopping-lists/{id}/shopping-list-items
PATCH,DELETE /shopping-lists/{id}/shopping-list-items/{id} | | TaxAppRestApi | StorefrontAPI | Planned | POST /tax-id-validate | | UpSellingProductsRestApi | StorefrontAPI | Planned | GET /carts/{id}/up-selling-products
GET /guest-carts/{id}/up-selling-products | | UrlsRestApi | StorefrontAPI | Planned | GET /url-resolver | | WishlistsRestApi | StorefrontAPI | Planned | GET,POST /wishlists
GET,PATCH,DELETE /wishlists/{id}
POST /wishlists/{id}/wishlist-items
PATCH,DELETE /wishlists/{id}/wishlist-items/{id} | ## Backend API modules All BackendAPI modules tracked in the migration scope. | Module | Category | Status | Key endpoints | |---|---|---|---| | CartNotesBackendApi | Extension-Only BackendAPI | Planned | SalesOrdersBackendApi | | CategoriesBackendApi | BackendAPI | Planned | GET,POST /categories
GET,PATCH /categories/{id} | | DynamicEntityBackendApi | BackendAPI | Planned | GET,POST,PATCH,PUT /dynamic-entity/{entity-name} (~62 auto-generated entity endpoints) | | OauthBackendApi | BackendAPI | Planned | POST /token | | PickingListsBackendApi | BackendAPI | Planned | GET /picking-lists
GET /picking-lists/{id}
PATCH /picking-lists/{id}/picking-list-items/{id}
POST /start-picking | | PickingListsUsersBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | PickingListsWarehousesBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | ProductAttributesBackendApi | BackendAPI | Planned | GET,POST /product-attributes
GET,PATCH /product-attributes/{id} | | ProductImageSetsBackendApi | BackendAPI | Planned | GET /concrete-product-image-sets | | ProductPackagingUnitsBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | ProductsBackendApi | BackendAPI | Planned | GET,POST /product-abstract
DELETE,GET,PATCH /product-abstract/{id} | | PushNotificationsBackendApi | BackendAPI | Planned | GET,POST /push-notification-providers
PATCH,DELETE /push-notification-providers/{id}
POST /push-notification-subscriptions | | SalesOrdersBackendApi | BackendAPI | Planned | GET /sales-orders | | ServicePointsBackendApi | BackendAPI | Planned | GET,POST /service-points
GET,PATCH /service-points/{id}
GET,POST /service-point-addresses
PATCH /service-points/{id}/service-point-addresses/{id}
GET,POST /service-types
GET,PATCH /service-types/{id}
GET,POST /services
GET,PATCH /services/{id} | | ShipmentTypesBackendApi | BackendAPI | Planned | GET,POST /shipment-types
GET,PATCH /shipment-types/{id} | | ShipmentsBackendApi | BackendAPI | Planned | GET /sales-shipments | | StoresBackendApi | BackendAPI | Planned | GET,POST,PATCH /stores | | UsersBackendApi | BackendAPI | Planned | GET /users | | WarehouseOauthBackendApi | BackendAPI | Planned | POST /warehouse-tokens | | WarehouseUsersBackendApi | BackendAPI | Planned | GET,POST /warehouse-user-assignments
GET,PATCH,DELETE /warehouse-user-assignments/{id} | | WarehousesBackendApi | BackendAPI | Planned | GET /warehouses |

AiFoundation module Overview

Tue, 05 May 2026 06:12:49 +0000

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

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

Architecture

The AiFoundation module uses a two-layer architecture:

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

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

Install the AiFoundation module

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

Configure AI providers

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

Best practice

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

Security

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

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

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

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

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

require 'config_ai.php';
```

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

Configuration structure

Each AI configuration requires:

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

Default configuration

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

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

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

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

Provider configuration examples

OpenAI

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

Anthropic Claude

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

AWS Bedrock

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

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

Ollama (local/self-hosted)

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

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

Run Ollama with Docker SDK

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

Create an ollama.yml file in your project root:

version: '3.8'

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

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

Update your AI configuration to use the Ollama service URL:

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

Deploy the changes:

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

Pull the required Ollama model:

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

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

Google Gemini

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

Deepseek

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

HuggingFace

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

Mistral AI

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

xAI Grok

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

Azure OpenAI

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

Use the AiFoundation facade

Basic usage

<?php

namespace Pyz\Zed\YourModule\Business;

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

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

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

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

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

Using a specific configuration

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

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

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

Multiple configurations example

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

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

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

Available provider constants

The module provides the following provider constants in AiFoundationConstants:

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

Transfer objects

PromptRequest

This transfer contains the request data for AI interaction:

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

PromptMessage

This transfer represents a message in the conversation:

content (string): The text content of the message
contentData (array, optional): Additional structured data
attachments (Attachment[], optional): File or image attachments
reasoning (string, optional): Model chain-of-thought reasoning returned alongside the response. Only populated when the provider returns reasoning blocks (for example, Anthropic extended thinking). null when the provider does not return reasoning.

PromptResponse

This transfer contains the AI response:

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

Attachment

This transfer represents a file or image attachment:

type (string): Type of attachment (use AiFoundationConstants::ATTACHMENT_TYPE_IMAGE or ATTACHMENT_TYPE_DOCUMENT)
content (string): The content—URL, Base64-encoded data, or a provider-hosted file ID
contentType (string): Content type format: ATTACHMENT_CONTENT_TYPE_URL, ATTACHMENT_CONTENT_TYPE_BASE64, or ATTACHMENT_CONTENT_TYPE_ID (for provider-hosted file references such as OpenAI or Anthropic Files API IDs)
mediaType (string): MIME type (for example, image/png, application/pdf)
filename (string, optional): Original filename for document attachments. Only set when the type is document and the caller provides it.

AWS Bedrock limitation

AWS Bedrock does not support URL-based attachments. When using AWS Bedrock as the provider, use ATTACHMENT_CONTENT_TYPE_BASE64 to pass image or document content as Base64-encoded data instead of a URL.

ToolInvocation

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

name (string): The name of the tool that was invoked
arguments (array): The arguments passed to the tool
result (string): The result returned by the tool execution
content (string, optional): Assistant text emitted alongside the tool call (for example, “I will use the calculator now.”). null when the model did not produce accompanying text.
reasoning (string, optional): Model chain-of-thought reasoning emitted alongside the tool call. null when the provider does not return reasoning blocks.

StructuredMessage

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

Conversation History

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

About NeuronAI framework

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

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

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

Install the Product Attribute Visibility feature

Mon, 04 May 2026 15:00:02 +0000

This document describes how to install the [Product Attribute Visibility feature](/docs/pbc/all/product-information-management/latest/base-shop/feature-overviews/product-feature-overview/product-attribute-visibility-overview.html). ## Prerequisites ### Install the required features | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | | Product | {{page.release_tag}} | [Install the Product feature](/docs/pbc/all/product-information-management/latest/base-shop/install-and-upgrade/install-features/install-the-product-feature.html) | ### Install the required packages | PACKAGE | VERSION | | --- | --- | | spryker-feature/product-experience-management | ^2.2.0 | | spryker/product-attribute | ^1.20.0 | | spryker/product-attribute-extension | ^1.2.0 | | spryker/product-attribute-gui | ^2.3.0 | | spryker/product-attribute-gui-extension | ^1.0.0 | | spryker/product-management | ^0.20.8 | | spryker-shop/cart-page | ^3.58.0 | | spryker-shop/catalog-page | ^1.36.0 | | spryker-shop/product-detail-page | ^3.31.0 | | spryker-shop/product-widget | ^1.6.0 | | spryker-shop/shop-ui | ^1.106.0 | ```bash composer require spryker/product-attribute:"^1.20.0" spryker/product-attribute-extension:"^1.2.0" spryker/product-attribute-gui:"^2.3.0" spryker/product-attribute-gui-extension:"^1.0.0" spryker-feature/product-experience-management:"^2.2.0" spryker/product-management:"^0.20.8" spryker-shop/cart-page:"^3.58.0" spryker-shop/catalog-page:"^1.36.0" spryker-shop/product-detail-page:"^3.31.0" spryker-shop/product-widget:"^1.6.0" spryker-shop/shop-ui:"^1.106.0" --update-with-dependencies --ignore-platform-req=ext-grpc ``` ## 1) Set up configuration Set up RabbitMQ and Symfony Messenger configuration for the publish and sync queues. **src/Pyz/Client/RabbitMq/RabbitMqConfig.php** ```php */ protected function getPublishQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE, ]; } /** * @return list */ protected function getSynchronizationQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_SYNC_STORAGE_QUEUE, ]; } } ``` **src/Pyz/Zed/Queue/QueueDependencyProvider.php** ```php */ protected function getProcessorMessagePlugins(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE => new EventQueueMessageProcessorPlugin(), ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_SYNC_STORAGE_QUEUE => new SynchronizationStorageQueueMessageProcessorPlugin(), ]; } } ``` **src/Pyz/Client/SymfonyMessenger/SymfonyMessengerConfig.php** ```php */ protected function getPublishQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE, ]; } /** * @return list */ protected function getSynchronizationQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_SYNC_STORAGE_QUEUE, ]; } } ``` ### Optional: Extend visibility types By default, the feature provides three visibility types: `PDP`, `PLP`, and `Cart`. To add project-specific visibility types, extend `ProductExperienceManagementConfig` at the project level and override the `getAvailableVisibilityTypes()` method. **src/Pyz/Shared/ProductExperienceManagement/ProductExperienceManagementConfig.php** ```php */ public function getAvailableVisibilityTypes(): array { return array_merge(parent::getAvailableVisibilityTypes(), [ static::VISIBILITY_TYPE_WISHLIST, ]); } } ``` After adding a custom visibility type, implement the corresponding widget or template logic in your Yves layer to render the attribute on the relevant page. ## 2) Set up the database schema and transfer objects 1. Create the following schema file to enable event-driven publishing for product management attributes: **src/Pyz/Zed/ProductAttribute/Persistence/Propel/Schema/spy_product_management_attribute.schema.xml** ```xml

``` 2. Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_product_management_attribute.visibility | column | created | | spy_product_attribute_storage | table | created | Make sure the following transfer objects have been generated: | TRANSFER | TYPE | EVENT | | --- | --- | --- | | ProductAttributeStorage | class | created | | ProductAttributeStorage.key | property | created | | ProductAttributeStorage.inputType | property | created | | ProductAttributeStorage.isSuper | property | created | | ProductAttributeStorage.visibilityTypes | property | created | | ProductManagementAttribute.visibility | property | created | | ProductManagementAttribute.visibilityTypes | property | created | | ProductManagementAttributeCollection | class | created | | ProductManagementAttributeCriteria | class | created | | ProductManagementAttributeConditions.productManagementAttributeIds | property | created | | ProductAttributeTableCriteria | class | created | | ProductAttributeTableCriteria.visibilityTypes | property | created | | ProductAttributeTableCriteria.withColumns | property | created | | ProductAttributeTableCriteria.queryConditions | property | created | | ProductAttributeTableCriteria.conditionCombineOperator | property | created | | ProductAttributeTableQueryCondition | class | created | | ProductAttributeQueryCriteria | class | created | | ProductAttributeQueryCriteria.withColumns | property | created | {% endinfo_block %} ## 3) Set up behavior ### Set up publisher and synchronization plugins Register the publisher and synchronization plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ProductAttributePublisherTriggerPlugin | Triggers a full publish of product attribute data. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\Publisher | | ProductAttributeWritePublisherPlugin | Handles create and update events for product attributes and writes data to storage. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\Publisher | | ProductAttributeSynchronizationDataBulkRepositoryPlugin | Provides product attribute storage data for the synchronization process. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\Synchronization | **src/Pyz/Zed/Publisher/PublisherDependencyProvider.php** ```php > */ protected function getPublisherPlugins(): array { return array_merge( parent::getPublisherPlugins(), $this->getProductAttributeStoragePlugins(), ); } /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherTriggerPluginInterface> */ protected function getPublisherTriggerPlugins(): array { return [ new ProductAttributePublisherTriggerPlugin(), ]; } /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherPluginInterface> */ protected function getProductAttributeStoragePlugins(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE => [ new ProductAttributeWritePublisherPlugin(), ], ]; } } ``` **src/Pyz/Zed/Synchronization/SynchronizationDependencyProvider.php** ```php */ protected function getSynchronizationDataStorePlugins(): array { return [ new ProductAttributeSynchronizationDataBulkRepositoryPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} Make sure that when you create or update a product attribute in the Back Office, the attribute data is published and synchronized to the `spy_product_attribute_storage` table: 1. In the Back Office, go to **Catalog > Attributes**. 2. Edit an attribute and change its **Display At** value. 3. Click **Save**. 4. Check that the `spy_product_attribute_storage` table contains the updated attribute data. {% endinfo_block %} ### Set up product attribute query expander Register the query expander plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | VisibilityProductAttributeQueryExpanderPlugin | Expands the product attribute query with the visibility column. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttribute | | VisibilitySuggestKeysQueryExpanderPlugin | Expands the suggest keys query with visibility filtering. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttribute | | VisibilitySuggestKeysExpanderPlugin | Expands the suggest keys result with visibility data. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttribute | **src/Pyz/Zed/ProductAttribute/ProductAttributeDependencyProvider.php** ```php */ protected function getProductAttributeQueryExpanderPlugins(): array { return [ new VisibilityProductAttributeQueryExpanderPlugin(), ]; } /** * @return list<\Spryker\Zed\ProductAttributeExtension\Dependency\Plugin\SuggestKeysQueryExpanderPluginInterface> */ protected function getSuggestKeysQueryExpanderPlugins(): array { return [ new VisibilitySuggestKeysQueryExpanderPlugin(), ]; } /** * @return list<\Spryker\Zed\ProductAttributeExtension\Dependency\Plugin\SuggestKeysExpanderPluginInterface> */ protected function getSuggestKeysExpanderPlugins(): array { return [ new VisibilitySuggestKeysExpanderPlugin(), ]; } } ``` ### Set up Back Office attribute form and table plugins Register the Back Office plugins for the attribute management UI: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | VisibilityAttributeTableConfigExpanderPlugin | Expands the attribute table configuration with the visibility column. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableHeaderExpanderPlugin | Adds the Display At header to the attribute table. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableDataExpanderPlugin | Renders visibility badges in attribute table rows. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableCriteriaExpanderPlugin | Adds visibility filter conditions to the attribute table query. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeFormExpanderPlugin | Adds the visibility types select field to the attribute form. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeFormDataProviderExpanderPlugin | Populates the attribute form with existing visibility data. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeFormTransferMapperExpanderPlugin | Maps visibility types from the form to the attribute transfer object. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableFilterFormExpanderPlugin | Adds a visibility type filter to the attribute table. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | **src/Pyz/Zed/ProductAttributeGui/ProductAttributeGuiDependencyProvider.php** ```php */ protected function getAttributeTableConfigExpanderPlugins(): array { return [ new VisibilityAttributeTableConfigExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableHeaderExpanderPluginInterface> */ protected function getAttributeTableHeaderExpanderPlugins(): array { return [ new VisibilityAttributeTableHeaderExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableDataExpanderPluginInterface> */ protected function getAttributeTableDataExpanderPlugins(): array { return [ new VisibilityAttributeTableDataExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableCriteriaExpanderPluginInterface> */ protected function getAttributeTableCriteriaExpanderPlugins(): array { return [ new VisibilityAttributeTableCriteriaExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeFormExpanderPluginInterface> */ protected function getAttributeFormExpanderPlugins(): array { return [ new VisibilityAttributeFormExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeFormDataProviderExpanderPluginInterface> */ protected function getAttributeFormDataProviderExpanderPlugins(): array { return [ new VisibilityAttributeFormDataProviderExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeFormTransferMapperExpanderPluginInterface> */ protected function getAttributeFormTransferMapperExpanderPlugins(): array { return [ new VisibilityAttributeFormTransferMapperExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableFilterFormExpanderPluginInterface> */ protected function getAttributeTableFilterFormExpanderPlugins(): array { return [ new VisibilityAttributeTableFilterFormExpanderPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} Make sure that the attribute management UI in the Back Office includes the visibility features: 1. In the Back Office, go to **Catalog > Attributes**. 2. Verify that the attribute table has a **Display At** column with visibility badges. 3. Verify that you can filter the table by visibility type using the filter dropdown. 4. Click **Edit** next to an attribute. 5. Verify that the attribute form includes a **Display At** field where you can select one or more visibility types. {% endinfo_block %} ## 4) Set up widgets Register the following global widgets: | WIDGET | DESCRIPTION | NAMESPACE | | --- | --- | --- | | ProductAttributeVisibilityPdpWidget | Displays product attributes configured for PDP visibility with schema.org structured data. | SprykerFeature\Yves\ProductExperienceManagement\Widget | | ProductAttributeVisibilityPlpWidget | Displays product attributes configured for PLP visibility as badges. | SprykerFeature\Yves\ProductExperienceManagement\Widget | | ProductAttributeVisibilityCartWidget | Displays product attributes configured for Cart visibility as badges. | SprykerFeature\Yves\ProductExperienceManagement\Widget | **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ ProductAttributeVisibilityPdpWidget::class, ProductAttributeVisibilityPlpWidget::class, ProductAttributeVisibilityCartWidget::class, ]; } } ``` ## 5) Set up Yves templates If you have overridden the default Twig templates at the project level, add the following widget calls to display product attributes on the Storefront. ### Product Detail Page (PDP) **src/Pyz/Yves/ProductDetailPage/Theme/default/components/molecules/product-detail/product-detail.twig** {% raw %} ```twig {% widget 'ProductAttributeVisibilityPdpWidget' args [data.product.idProductAbstract, data.product.idProductConcrete | default(null),] only %} {% nowidget %} {% endwidget %} ``` {% endraw %} ### Product Listing Page (PLP) **src/Pyz/Yves/ProductWidget/Theme/default/components/molecules/catalog-product/catalog-product.twig** {% raw %} ```twig {% widget 'ProductAttributeVisibilityPlpWidget' args [data.products, data.product.idProductAbstract] only %} {% nowidget %} {% endwidget %} ``` {% endraw %} If you have overridden `Yves/CatalogPage/Theme/default/templates/page-layout-catalog/page-layout-catalog.twig` at the project level, update the `CatalogPageProductWidget` call to pass `data.products` as an additional argument: **src/Pyz/Yves/CatalogPage/Theme/default/templates/page-layout-catalog/page-layout-catalog.twig** {% raw %} ```twig {% widget 'CatalogPageProductWidget' args [product, data.viewMode, data.products] with { ``` {% endraw %} If you have overridden `Yves/ShopUi/Theme/default/components/molecules/product-item/product-item.twig` or `Yves/ShopUi/Theme/default/components/molecules/product-item-list/product-item-list.twig` at the project level, add the following block to each template in the location where the widget should be rendered: **src/Pyz/Yves/ShopUi/Theme/default/components/molecules/product-item/product-item.twig** **src/Pyz/Yves/ShopUi/Theme/default/components/molecules/product-item-list/product-item-list.twig** {% raw %} ```twig {% block productAttributeVisibility %}{% endblock %} ``` {% endraw %} ### Cart **src/Pyz/Yves/CartPage/Theme/default/components/molecules/product-cart-item/product-cart-item.twig** {% raw %} ```twig {% widget 'ProductAttributeVisibilityCartWidget' args [data.cart is iterable ? null : data.cart, data.product.idProductAbstract, data.product.idProductConcrete] only %} {% nowidget %} {% endwidget %} ``` {% endraw %} {% info_block warningBox "Verification" %} Make sure the product attributes are displayed on the Storefront based on their visibility configuration: 1. In the Back Office, configure an attribute with **PDP** visibility. 2. On the Storefront, open the product detail page and verify the attribute is displayed. 3. Configure an attribute with **PLP** visibility and verify it appears as a badge on the product listing page. 4. Configure an attribute with **Cart** visibility and add the product to the cart. Verify the attribute badge is displayed in the cart. {% endinfo_block %} ## 6) Set up data import ### Add facade dependencies Register the required facade dependencies in the data import module. **src/Pyz/Zed/DataImport/DataImportDependencyProvider.php** ```php addProductExperienceManagementFacade($container); return $container; } protected function addProductExperienceManagementFacade(Container $container): Container { $container->set(static::FACADE_PRODUCT_EXPERIENCE_MANAGEMENT, function (Container $container) { return $container->getLocator()->productExperienceManagement()->facade(); }); return $container; } } ``` ### Update the product management attribute writer Extend `ProductManagementAttributeWriter` to handle the `visibility` column during import. The writer saves the visibility value to the `spy_product_management_attribute` table, triggers a publish event, and validates visibility types against the allowed values. **src/Pyz/Zed/DataImport/Business/Model/ProductManagementAttribute/ProductManagementAttributeWriter.php** ```php normalizeVisibility($visibility, $dataSet['key']); } $productManagementAttributeEntity ->setAllowInput($dataSet['allow_input']) ->setInputType($dataSet['input_type']) ->setVisibility($visibility); $productManagementAttributeEntity->save(); $this->addPublishEvents( ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_PUBLISH, $productManagementAttributeEntity->getIdProductManagementAttribute(), ); // ... existing logic for attribute values ... } protected function normalizeVisibility(string $visibility, string $attributeKey): string { $visibilityTypes = array_map('trim', explode(',', $visibility)); $allowedVisibilityTypes = $this->productExperienceManagementFacade->getAvailableVisibilityTypes(); $allowedVisibilityTypesMap = array_combine( array_map('strtolower', $allowedVisibilityTypes), $allowedVisibilityTypes, ); $normalized = []; foreach ($visibilityTypes as $visibilityType) { $canonical = $allowedVisibilityTypesMap[strtolower($visibilityType)] ?? null; if ($canonical === null) { throw new DataImportException( sprintf( 'Invalid visibility type "%s" for attribute "%s". Allowed: %s (or empty).', $visibilityType, $attributeKey, implode(', ', $allowedVisibilityTypes), ), ); } $normalized[] = $canonical; } return implode(',', $normalized); } } ``` Wire the facade into the writer via the business factory. **src/Pyz/Zed/DataImport/Business/DataImportBusinessFactory.php** ```php addStep(new ProductManagementAttributeWriter()); // with: // ->addStep(new ProductManagementAttributeWriter( // $this->getProductExperienceManagementFacade(), // )); protected function getProductExperienceManagementFacade(): ProductExperienceManagementFacadeInterface { return $this->getProvidedDependency(DataImportDependencyProvider::FACADE_PRODUCT_EXPERIENCE_MANAGEMENT); } } ``` ### Prepare and import data 1. Add the `visibility` column to the existing `product_management_attribute.csv` file. File: **data/import/common/common/product_management_attribute.csv** ```csv key,input_type,allow_input,is_multiple,values,key_translation.en_US,key_translation.de_DE,value_translations.en_US,value_translations.de_DE,visibility storage_capacity,text,no,no,"16 GB, 32 GB, 64 GB, 128 GB",Storage Capacity,Speichergröße,,,PDP color,text,no,yes,"white, black, grey",Color,Farbe,"white, black, grey","weiß, schwarz, grau","PDP,PLP,Cart" brand,text,yes,no,,Brand,Marke,,,PDP internal_sku,text,yes,no,,Internal SKU,Interne SKU,,,, ``` | COLUMN | REQUIRED | DATA TYPE | DATA EXAMPLE | DATA EXPLANATION | | --- | --- | --- | --- | --- | | key | ✓ | string | color | Unique attribute key. | | input_type | ✓ | string | text | Input type for the attribute. | | allow_input | ✓ | string | no | Whether custom input is allowed. | | is_multiple | ✓ | string | no | Whether multiple values are supported. | | values | | string | "white, black, grey" | Predefined attribute values. | | visibility | | string | "PDP,PLP,Cart" | Comma-separated list of visibility types. Valid values: `PDP`, `PLP`, `Cart`. Leave empty for internal-only attributes. | 2. Import data: ```bash console data:import product-management-attribute ``` {% info_block warningBox "Verification" %} Make sure that the product attribute visibility data is imported correctly: 1. In the Back Office, go to **Catalog > Attributes**. 2. Verify that each attribute displays the correct visibility types in the **Display At** column. 3. Check that the `spy_product_management_attribute` table contains the correct `visibility` values. {% endinfo_block %}

Release notes 202604.0

Mon, 04 May 2026 14:12:48 +0000

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). ## B2B Business-Ready Commerce Experiences ### Back Office Configuration Framework is now Generally Available {% include badge.html type="feature" %} Spryker has made the Back Office Configuration Framework generally available, delivering key enterprise‑readiness improvements. The release enhances governance, discoverability, and usability for managing business‑relevant configuration directly in the Back Office. Configuration changes are now easier to understand, control, and audit. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/backoffice_framework.png||" %} **Key capabilities:** - Audit logging for configuration changes - Improved search and discoverability of configuration options - UX enhancements for a more reliable configuration experience - CLI-based import support for faster setup and operational workflows - Clear visibility into conflicts between code-based and Back Office configuration **Business benefits:** - Reduces time-to-change by enabling operations teams to adjust configuration without developer involvement, backed by a full audit trail. - Minimizes the risk of costly production disruptions through better validation and conflict visibility before changes go live. - Supports broader enterprise adoption with stronger governance and operability. **Documentation:** - [Back Office Configuration Framework](/docs/pbc/all/back-office/latest/base-shop/backoffice-configuration-framework.html) - [Developer Guide Configuration Management](/docs/dg/dev/backend-development/configuration-management) - [Install the Back Office Configuration Framework feature](/docs/dg/dev/integrate-and-configure/integrate-confguration-feature.html) ### Basic Shop Theming {% include badge.html type="feature" %} Business users can now manage core branding settings directly in the Back Office without code changes or deployments. This provides a standardized way to apply basic theming across Storefront, the Back Office, and Merchant Portal. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/theming_1.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/theming_2.png||" %} **Key capabilities:** - Supports theme management with global and store-specific scope. - Lets users upload and manage logos for Storefront, the Back Office, and Merchant Portal. - Provides configuration for core brand colors, button styles and text colors. - Uses a standardized Back Office configuration experience for theme administration. **Business benefits:** - Speeds up demo preparation, POCs, and early customer activation through instant, self-service branding configuration. - Shop operators can now apply and adjust their brand CI across all Spryker touchpoints at any time directly in the Back Office, without developer involvement or redeployment. **Documentation:** - [Feature Overview](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/purchasing-control-feature-overview.html) - [Installation Guide](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-purchasing-control-feature.html) ### Budget & Cost Centers {% include badge.html type="feature,early-access" %} We introduced an Early Access version of budgets and cost centers to support policy-driven purchasing in B2B procurement. The release covers core budget enforcement and its integration with approval workflows. **Key capabilities:** - Lets companies create and manage cost centers and assign buyers to them. - Supports budget creation with configurable enforcement rules such as block, warn, or require approval. - Adds cost center selection and budget validation during checkout. - Integrates budget-triggered approvals with Spryker's existing Approval Process. - Tracks budget consumption and restoration as orders progress. **Business benefits:** - Improves financial control and purchasing compliance. - Reduces overspending risk with enforceable budget rules. - Aligns procurement workflows with departmental or project-based spending structures. - Provides an early demoable foundation for customer and partner conversations. **Documentation:** - [Purchasing Control Feature Overview](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/purchasing-control-feature-overview) - [Install Purchasing Control Feature Overview](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-purchasing-control-feature) ### Back Office Product Import & Export {% include badge.html type="feature,early-access" %} Spryker now offers product import and export via the Back Office, reducing reliance on developer‑driven CLI tooling. Business users can prepare and update catalogs faster during onboarding, launches, and routine maintenance. This improves operational speed and gives teams more control over their product data processes. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/bo_import_export_1.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/bo_import_export_2.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/bo_import_export_3.png||" %} **Key capabilities:** - Import and export product data directly from the Back Office - Single‑file product import, replacing multiple CLI‑required files - CSV‑based jobs with reusable job/run concepts and clear validation feedback **Business benefits:** - Significantly simplifies adding products to the catalog, replacing multi‑file CLI imports with a single, business‑friendly file - Accelerates catalog preparation for new launches and environment migrations - Empowers business users with self‑service error resolution, minimizing developer involvement **Documentation:** - [Product Experience Management](/docs/pbc/all/product-experience-management/latest/product-experience-management.html) - [Install the Product Experience Management feature](/docs/pbc/all/product-experience-management/latest/install-the-product-experience-management-feature.html) ### Product attribute display types {% include badge.html type="feature" %} You can now control where product attributes are visible without project-specific customization. This helps keep internal operational data hidden while displaying only relevant information to buyers. **Key capabilities:** - Adds visibility types for product attributes. - Supports internal-only attributes as well as attributes shown on PDP, PLP, and cart-related experiences. - Provides native configuration for attribute visibility management. **Business benefits:** - Shop operators can now control which attributes are displayed where across the storefront, making it easier to surface the right product information at the right place to support buyer decision-making and product discovery. - Internal attributes can be managed separately to support operational or process-related needs without ever being exposed to buyers. **Documentation:** - [Product Attribute Display Types](/docs/pbc/all/product-information-management/latest/base-shop/feature-overviews/product-feature-overview/product-attribute-visibility-overview) - [Install Product Attribute Visibility Feature](/docs/pbc/all/product-information-management/latest/base-shop/install-and-upgrade/install-features/install-the-product-attribute-visibility-feature) ### Spryker Storefront Design System Foundation {% include badge.html type="feature" %} Building storefronts without a common foundation meant repeated work, slower delivery, and experiences that looked and felt different every time. This release introduces a unified design system with shared foundations and reusable components, so teams work from common building blocks. The result is faster implementation, easier adoption, and the ability to scale storefront delivery without scaling complexity. **Key capabilities:** - Defines the design system foundation with shared tokens and naming conventions. - Introduces token-driven implementation patterns for new storefront components. - Adds composite component patterns built from core UI elements. - Covers common structures such as cards, buttons, input fields, headers, search and more. **Business benefits:** - Improves consistency across storefront experiences. - Reduces duplicate design and frontend implementation effort. - Accelerates feature delivery with reusable UI patterns. - Creates a stronger foundation for future storefront evolution. **Documentation:** - [How to use design system tokens](/docs/dg/dev/frontend-development/latest/design-tokens#how-it-works) ### Back Office support for merchant product ownership {% include badge.html type="improvement" %} Marketplace operators can now manage merchant ownership of products directly in the Back Office, without relying on the Merchant Portal. This makes it easier to maintain accurate product data in centrally managed or hybrid marketplace models. The result is smoother operations and clearer accountability across the catalog. **Key capabilities:** - Assign or update merchant ownership for any product directly in Back Office workflows. - See merchant ownership instantly within product management views. - Maintain merchant‑related product data as part of your standard PIM processes. **Business benefits:** - Strengthens support for centrally managed catalogs and hybrid marketplace models, giving operators more flexibility in how they run their marketplace. - Improves transparency and control, making ownership clear, consistent, and auditable. - Reduces reliance on workarounds and custom tooling, lowering operational overhead. - Supports more flexible marketplace operations, enabling teams to scale product management with confidence. **Documentation:** - [Marketplace Create Abstract Products](/docs/pbc/all/product-information-management/latest/marketplace/manage-in-the-back-office/products/abstract-products/create-abstract-products#defining-general-settings) ### Back Office Frontend Modernisation {% include badge.html type="improvement" %} We delivered the first phase of the Back Office theme modernisation to improve clarity, consistency, and responsiveness. This update creates a more usable and scalable visual foundation without changing the overall information architecture. **Key capabilities:** - Improves visual hierarchy and component consistency across the Back Office. - Reduces UX debt introduced by legacy Inspinia defaults. - Enhances spacing, density, emphasis, and table presentation. - Provides a more stable foundation for future Back Office UX improvements. **Business benefits:** - Improves daily usability for Back Office users. - Makes the Back Office more credible and demo-ready. - Reduces the need for one-off CSS customizations. - Establishes a better base for future product evolution. ### Streamlined Login and Session Recovery Experience {% include badge.html type="improvement" %} Logging in should feel like picking up where you left off, not starting over. With this release, users across the Back Office, Storefront, and Marketplace are presented with a meaningful dashboard featuring quick actions for common tasks, including viewing orders, adding products, and checking returns. After a session timeout, users are redirected back to the page they were on so they do not lose track of what they were doing. **Key capabilities:** - Redirects Back Office users to the dashboard instead of a blank technical page after login. - Adds action-oriented quick actions to the Back Office dashboard for common tasks such as viewing orders, adding products, opening the catalog, and checking returns. - Restores the last visited page after session timeout across the Back Office, Storefront, and Marketplace. - Reopens create and edit pages after re-login, while unsaved data is not preserved. **Business benefits:** - Reduces onboarding friction for new users. - Helps operational users continue workflows faster after session expiration. - Improves usability and perceived product maturity across core daily journeys. - Makes demos and first-touch product experiences more intuitive. ## Connected, and AI-Enabled Platform ### Spryker Now Ships with AI Foundation and Smart Product Enrichment {% include badge.html type="improvement,early-access" %} Spryker now includes the AI Foundation and Smart PIM out of the box, allowing merchants to adopt AI‑assisted catalog enrichment with minimal setup. Product content can be improved, translated, and enriched directly in the Back Office using AI, reducing manual work and improving content quality. Customers only need to connect their preferred AI provider to start benefiting from AI‑powered product enhancements, with governance automatically handled through AI Foundation. **Key capabilities** - Enhances and translates product names and descriptions using AI - Generates alt‑text for product images and suggests suitable product categories - Delivered by default in Spryker, requiring only AI provider configuration **Business benefits** - Reduces manual effort in creating and refining product content across the catalog - Makes AI adoption easier by providing a pre‑configured integration layer with built‑in governance and provider flexibility - Speeds up catalog enrichment and localization for merchants operating across multiple markets **Documentation** - [AI Foundation Overview](/docs/dg/dev/ai/ai-foundation/ai-foundation-module) - [Smart PIM](/docs/pbc/all/ai-commerce/latest/smart-pim) ### Smart Back Office Assistant {% include badge.html type="feature,early-access" %} Spryker introduces the Smart Back Office Assistant, enabling operators to perform Back Office tasks through natural language instead of relying solely on manual navigation. Operators can get guidance on where to find features, ask operational and order‑related questions, and create discounts directly through chat. This makes Back Office work faster, more intuitive, and easier for all user types. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/bo_ai_assistant.png||" %} **Key capabilities** - Provides navigation and operational guidance to help users quickly find functions and understand Back Office workflows - Answers order‑related questions, including order status and operational details - Assists to complete forms, for example, by enabling discount creation directly through chat. **Business benefits** - Reduces time spent searching for pages and completing repetitive tasks - Improves usability for operators who are less familiar with Back Office structure or workflows - Helps prevent errors by guiding operators through correctly structured inputs and actions **Documentation** - [Back Office Assistant](/docs/dg/dev/ai/ai-commerce/ai-commerce-overview.html) - [Install Back Office Assistant](/docs/dg/dev/ai/ai-commerce/backoffice-assistant/install-backoffice-assistant.html) ### AI Foundation Visibility & Governance Enhancements {% include badge.html type="feature,early-access" %} Spryker introduces comprehensive visibility into AI activity through new Back Office views for both AI interactions and AI workflow execution. Teams can now inspect prompts, responses, metadata, and workflow states in a single place, improving transparency and control over AI‑driven processes. These enhancements strengthen governance, streamline troubleshooting, and make AI operations easier to understand and monitor. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/bo_ai_auditlogs_1.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/bo_ai_auditlogs_2.png||" %} **Key capabilities:** - Back Office audit logs for reviewing prompts, responses, metadata, and model details - Workflow execution views with list, detail, state history, and visualized transitions - Filtering, sorting, and inline inspection tools for efficient debugging and analysis **Business benefits:** - Improves governance and traceability across all AI‑powered processes - Simplifies troubleshooting by making AI interactions and workflow states fully transparent - Gives operators greater control over AI‑driven actions with clear visibility into execution paths **Documentation:** - [AI Foundation Audit Logs](/docs/dg/dev/ai/ai-foundation/ai-foundation-audit-logs.html) - [AI Foundation Workflows](/docs/dg/dev/ai/ai-foundation/ai-foundation-workflow-state-machine) ### Smart Visual Product Search & Ordering {% include badge.html type="improvement,early-access" %} Spryker now enables buyers to identify products and start orders simply by uploading or capturing an image. Whether it's a technical part, a field-site photo, or a handwritten note, the system can recognize products and quantities and help buyers move directly from identification to ordering. The entire capability now runs on the Spryker AI Foundation, offering provider flexibility, improved reliability, and easier long‑term adoption. **Key capabilities** - Helps buyers identify relevant or visually similar products by uploading or capturing an image - Prefills the quick order form with products and quantities extracted from photos, screenshots, or handwritten notes - Uses Spryker AI Foundation for multi‑provider support (OpenAI, Azure, Bedrock) and centralized AI governance **Business benefits** - Speeds up product identification and ordering, especially for technical and spare‑parts workflows - Reduces manual entry and ordering errors by interpreting product information directly from images - Supports mobile and field‑based buying scenarios where buyers capture photos instead of searching by name or SKU **Documentation** - [Search by Image](/docs/pbc/all/ai-commerce/latest/search-by-image) - [Visual Add to Cart](/docs/pbc/all/ai-commerce/latest/visual-add-to-cart) - [Install Search by Image](/docs/dg/dev/ai/ai-commerce/search-by-image/install-search-by-image) - [Install Visual Add to Cart](/docs/dg/dev/ai/ai-commerce/visual-add-to-cart/install-visual-add-to-cart) ### AI Dev Tooling for Coding Agents {% include badge.html type="feature,early-access" %} Spryker now provides ready-to-use new AI Dev tooling to help development teams work more effectively with coding agents in Spryker projects. The update provides ready-to-use agent instruction files and reusable Spryker-specific skill examples. **Key capabilities:** - Generates a project‑ready agent configuration file (AGENTS.md) - Generates a set of rules for AI agent based on Spryker coding conventions and architectural guidelines - Provides reusable skill examples covering testing, data import, schema conventions, validation, and frontend development - Includes a setup command that generates agent configuration file, rules and skills for supported coding agents **Business benefits:** - Speeds up onboarding for developers who are new to Spryker by giving AI coding agents the right context from day one - Improves code quality and consistency through pre‑written, Spryker‑aligned development rules - Helps teams deliver features faster by reducing back‑and‑forth with AI tools and minimizing incorrect code generation **Documentation:** - [AI Dev SDK](/docs/dg/dev/ai/ai-dev/ai-dev-overview) ### API Platform is now Generally Available {% include badge.html type="feature" %} Spryker made API Platform generally available as the foundation for modern API development and migration. Existing APIs have been migrated to API Platform internally while keeping external contracts backward-compatible. This enables faster API delivery, easier extensibility, and more standardized API development. ![API Platform](https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202512/api-platform-2.6-api.png) **Key capabilities:** - Declarative API development using YAML schemas - API generation with validation, pagination, serialization, and operation-specific rules - Interactive and always up-to-date OpenAPI documentation - Backward-compatible migration of existing APIs to API Platform infrastructure - Cleaner separation of read and write logic through providers and processors **Business benefits:** - Reduces development effort for new and existing APIs - Improves consistency and maintainability of API implementations - Accelerates delivery of integrations and future API capabilities **Documentation:** - [API Platform](/docs/dg/dev/architecture/api-platform.html) - [Migration Status of out-of-the-box API Endpoints](/docs/dg/dev/architecture/api-platform/migrate-to-api-platform-status.html) ### Algolia configuration in the Back Office {% include badge.html type="improvement" %} Spryker updated the Algolia integration settings in the Back Office to replace the legacy ACP-based configuration experience. The new page uses the Back Office Configuration Framework and provides a more consistent and user-friendly way to manage Algolia credentials. This helps reduce setup effort and simplifies validation during implementation. **Key capabilities:** - New configuration section in **Back Office > Configuration > Integrations > Algolia** - Manage Algolia credentials, including: - Application ID - Search-only API key - Admin API key - Validate credentials directly via API calls - Align Algolia setup with the current Spryker-native integration approach **Business benefits:** - Simplifies Algolia setup and maintenance in the Back Office - Reduces implementation time and configuration errors - Replaces legacy ACP-era fields with a clearer configuration experience **Documentation:** - [Integrate Algolia](/docs/pbc/all/search/latest/base-shop/third-party-integrations/algolia/integrate-algolia) ### Mollie PSP Integration {% include badge.html type="feature" %} Spryker introduces a new native integration with Mollie, a leading European payment service provider, enabling seamless B2B and B2C payment experiences across key European markets. The integration allows merchants to quickly enable a wide range of local and international payment methods with minimal development effort. It is delivered in collaboration with Spryker Solution Partner KPS. **Key capabilities:** - Native integration with Mollie - Support for a wide range of local European and international payment methods - Plug-and-play setup with minimal custom development **Business benefits:** - Faster time-to-market for European commerce use cases - Improved conversion through localized payment experiences - Reduced implementation complexity and maintenance overhead **Documentation:** - [Mollie integration](https://github.com/mollie/spryker) ### OAuth SSO readiness for Spryker applications {% include badge.html type="feature" %} Spryker introduced a standardized and reusable approach for OAuth 2.0 and OpenID Connect single sign-on across key applications. The release establishes a consistent integration pattern for identity providers such as Keycloak, Azure AD, and Okta for the Back Office, Storefront, and Merchant Portal. This makes identity integrations more predictable and reduces the need for project-specific implementations. **Key capabilities:** - Standardized SSO approach for: - the Back Office - Storefront - Merchant Portal - Support for OAuth Authorization Code flow with PKCE - Provider-agnostic integration based on configurable OAuth providers - Persistent identity linking between external providers and Spryker users - Reference implementation, templates, configuration patterns, and rollout guidance - Backward compatibility with existing form-based login **Business benefits:** - Reduces time and cost for enterprise identity integrations - Improves implementation predictability across projects - Creates a reusable foundation for federated authentication across Spryker entry points **Documentation:** - [Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/federated-authentication.html) ### Native PunchOut Gateway for cXML and OCI {% include badge.html type="feature,early-access" %} Spryker introduced native PunchOut Gateway capabilities for cXML and OCI to reduce bespoke integration work in procurement-driven B2B commerce. The release adds reusable building blocks for common PunchOut flows, including session start, shopping, cart updates, and cart return. This strengthens support for enterprise procurement environments, especially SAP-centric setups. **Key capabilities:** - Native compatibility for cXML and OCI PunchOut scenarios - Support for basic PunchOut requisition and cart flows - Standard OCI parameter handling - OCI cart return support with line items - Reusable message handling and implementation guidance **Business benefits:** - Reduces custom development effort for PunchOut implementations - Speeds up procurement-channel enablement and time-to-revenue - Improves repeatability and maintainability across B2B integration projects **Documentation:** - [PunchOut Gateway](/docs/pbc/all/punchout-gateway/punchout-gateway) ### New Stripe Integration {% include badge.html type="improvement" %} Spryker introduced a new Stripe integration that replaces the legacy ACP-based app with a more extensible Spryker-native implementation. The release also adds a dedicated configuration page in the Back Office for managing Stripe settings. This gives customers and partners more control over Stripe-based payment flows and reduces dependency on legacy integration boundaries. **Key capabilities:** - New installable Stripe Eco module without ACP runtime dependency - Support for checkout payment method selection - Support for payment initialization, authorization, capture, refund, and cancel flows - New configuration section in **Back Office > Configuration > Integrations > Stripe** - Validation of Stripe keys and webhook configuration - Storage of Stripe settings in configuration storage **Business benefits:** - Improves flexibility for extending and customizing Stripe payment flows - Reduces implementation risk and legacy dependency overhead - Lowers long-term maintenance effort and supports faster payment innovation **Documentation:** - [New Stripe Integration](https://github.com/spryker-eco/stripe/releases/tag/1.0.0) ### New Vertex Integration {% include badge.html type="improvement" %} Spryker introduced a new Vertex integration to replace the legacy ACP-based approach for tax calculation scenarios. The new integration is designed to provide more flexibility and reduce legacy constraints when adapting tax-related processes. This supports more maintainable and extensible tax integrations over time. **Key capabilities:** - New Spryker-native Vertex integration - Reduced reliance on legacy ACP-based architecture - Improved extensibility for tax calculation and related scenarios **Business benefits:** - Supports more adaptable tax integrations for changing business needs - Reduces integration friction and project-specific patching - Lowers total cost of ownership through improved maintainability **Documentation:** - [Integrate Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex) ### Data import performance and stability enhancements {% include badge.html type="improvement" %} We improved the data import experience and robustness for large data volumes. Data imports now provide better execution visibility through a progress bar, and memory usage has been optimized to better support very large imports, including merchant price imports with up to 1 million records. **Key capabilities:** - Added a progress bar for data import console commands to show execution progress. - Reduced memory consumption in data import flows to prevent out-of-memory issues during large imports. - Improved reliability for high-volume imports across data import entities. **Business benefits:** - Helps operators better monitor long-running imports. - Reduces failures caused by memory exhaustion during large imports. - Improves operational efficiency for bulk data onboarding. **Documentation:** - [Data import (memory usage)](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html#data-import-memory-usage) - [Data import Progress bar](/docs/dg/dev/data-import/latest/data-import-optimization-guidelines.html#progress-bar) ### Performance and security improvements {% include badge.html type="improvement" %} We made your Spryker Commerce OS faster, more secure, and more stable. **Key capabilities:** - Non-buffered log streaming presents the logs immediately. - Lower latency and response times in storefront with optimized widgets. - Lower latency and response times in the Back Office and Merchant Portal. - Higher stability and throughput of Publish & Synchronize workers. The update introduces dynamic waiting behavior, better control over parallel job execution, and compatibility improvements for Symfony Messenger resource-aware workers. **Documentation:** - [Non-buffered log streaming](https://api.release.spryker.com/release-group/6411) - [Yves widget performance best practices](/docs/dg/dev/guidelines/performance-guidelines/yves-performance-best-practice.html) - [Split Publish & Synchronize queues for performance](/docs/dg/dev/guidelines/performance-guidelines/split-queues-performance.html) - [Merchant Portal and Back Office performance with ACL rules](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html#merchant-portal-and-back-office-performance-with-acl-rules) - [Order details page performance guidance](/docs/pbc/all/order-management-system/latest/base-shop/order-management-feature-overview/order-details-page-performance-overview.html) ## Efficient and Flexible Cloud Foundation ### Spryker Monitoring Integration: logs forwarding {% include badge.html type="improvement" %} Spryker expanded cloud observability by enabling log forwarding through [SMI](/docs/ca/dev/monitoring/spryker-monitoring-integration/spryker-monitoring-integration.html) to third-party monitoring platforms of your choice. This allows teams to correlate logs with traces, create alerts based on log data, and use their preferred monitoring tooling beyond AWS CloudWatch. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/SMI-dynatrace-logs.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202604/SMI-dynatrace-traces.png||" %} **Key capabilities:** - Inspect logs from Spryker Platform in your monitoring tool - Correlate logs with traces using trace and span identifiers - Configure log verbosity to control emitted log volume **Business benefits:** - Improved troubleshooting through unified logs and traces - Better alerting capabilities based on application and infrastructure log events **Documentation:** - [Spryker Monitoring Integration Logs](/docs/ca/dev/monitoring/spryker-monitoring-integration/opentelemetry-instrumentation#smi-logs-integration) ### Single Sign-On (SSO) for Cloud services {% include badge.html type="feature" %} Spryker introduced centralized access management for cloud services, including SSO support for customer identity providers such as Okta and OneLogin. This update reduces manual access handling, improves security, and simplifies onboarding and offboarding for users. It also includes rollout, production-readiness, and IAM cleanup measures to standardize and harden access controls.

**Key capabilities:** - Connect your own identity provider for SSO access to cloud services - Centralize user access management for services such as Jenkins, RabbitMQ, and others - Reduce manual access management effort through self-service-oriented processes **Business benefits:** - Faster and more secure user onboarding and offboarding - Reduced operational effort for access requests and changes - TLS-encrypted communication to Jenkins and RabbitMQ over internal environment network **Documentation:** - [Spryker Cloud SSO Access](/docs/ca/dev/access/sso-access.html) ### Bastion security hardening {% include badge.html type="improvement" %} Spryker improved Bastion host security and maintainability by upgrading the operating system, isolating workloads from the host, and enforcing SSO and MFA for human access. This change modernizes the setup while keeping customer impact minimal and preserving SFTP access for integrations. **Key capabilities:** - Upgrade Bastion hosts to a current LTS operating system - Enforce SSO and MFA for human access, deprecate direct SSH access for human users **Business benefits:** - Improved security posture for administrative access ### Maintenance and service updates {% include badge.html type="improvement" %} Spryker delivered maintenance updates across cloud services and application tooling to keep the platform secure, supported, and maintainable. **Key capabilities:** - RabbitMQ 4.2 is now supported in Docker SDK for local development environments. - Node.js 24 introduces V8 v13.6 and npm 11, which results in noticeably faster `frontend:yves:build` and `frontend:zed:build` runs. **Business benefits:** - Reduced security and operational risk from outdated components **Documentation:** - [RabbitMQ 4.2 in Docker SDK](/docs/dg/dev/sdks/the-docker-sdk/the-docker-sdk.html) - [Upgrade Node.js and npm](/docs/dg/dev/upgrade-and-migrate/upgrade-nodejs.html#prerequisites)

Enable Dynamic Multistore

Mon, 04 May 2026 13:36:43 +0000

This document describes how to enable Dynamic Multistore (DMS).

Prerequisites

If your project version is below 202307.0, Install Dynamic Multistore.

Enable Dynamic Multistore

Staging environment

To avoid unexpected downtime and data loss, perform and test *all* of the following steps in a staging environment first.

Replace StoreClient::getCurrentStore() and StoreFacade::getCurrentStore() methods with StoreStorageClient:getStoreNames(), StoreStorageClient::findStoreByName(), or StoreFacade::getStoreCollection() in the following:

Back Office
Merchant Portal
Console Commands
Gateway
BackendAPI

Update custom console commands to meet the following rules:

Store(Facade|Client)::getCurrentStore() isn’t used in the code a console command executes.
All store-aware commands implement Spryker\Zed\Kernel\Communication\Console\StoreAwareConsole and execute actions for a specific store if a store parameter is provided; if not provided, actions are executed for all the stores in the region.
Optional: We recommend using the --store parameter instead of APPLICATION_STORE env variable; both methods are supported.

After enabling DMS, the basic domain structure must change from store to region for all the applications. For example, https://yves.de.mysprykershop.com will change to https://yves.eu.mysprykershop.com. To prevent negative SEO effects, set up the needed redirects. If your target domain doesn’t change, for example it doesn’t contain a region name - yves.mysprykershop.com - you may skip this step.
Create a support case and provide the deploy.yml file that contains the dynamic multistore setup. For example: “We have added the dynamic multistore setup to our deploy.yml and would like it to be activated.”
DMS changes the structure of RabbitMQ messages. When you’re ready for the migration, wait for all the remaining messages in the queue to be processed. When the queue is empty, enable the maintenance mode.

The downtime associated with the maintenance mode is limited to the deployment time, which usually takes up to an hour.

Update AWS deployment files to DMS mode using the example:

Original environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy.dynamic-store-off -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r production.dynamic-store-off --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive.dynamic-store-off --no-ansi -vvv'
SPRYKER_YVES_HOST_DE: de.
SPRYKER_YVES_HOST_AT: at.

Updated environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r dynamic-store --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive --no-ansi -vvv'
SPRYKER_DYNAMIC_STORE_MODE: true
SPRYKER_YVES_HOST_EU: yves.eu.

Original regions section:

regions:
  stores:
    DE:
      services:
        broker:
          namespace: de_queue
        key_value_store:
          namespace: 1
        search:
          namespace: de_search
        session:
          namespace: 2
    AT:
      services:
        broker:
          namespace: at_queue
        key_value_store:
          namespace: 3
        search:
          namespace: at_search
        session:
          namespace: 4

Updated regions section:

regions:
  broker:
    namespace: eu-docker
  key_value_store:
    namespace: 1
  search:
    namespace: eu_search

Run a normal deploy for your server pipeline.

Verification

- Make sure your store is available at `https://yves.eu.mysprykershop.com` or `https://backoffice.eu.mysprykershop.com`. - Make sure the store switcher is displayed on the Storefront.

Your shop is now running in DMS mode.

Check if Dynamic Multistore is enabled

DMS is enabled if at least one of the following applies:

Using environment: If the value of SPRYKER_DYNAMIC_STORE_MODE environment variable is true
Using interface: In the Back Office > Administration > Stores, an Edit button is displayed next to each store.

Disable Dynamic Multistore

Staging environment

To avoid unexpected downtime and data loss, perform and test *all* of the following steps in a staging environment first.

After disabling DMS, the basic domain structure will change from region to store for all the applications. To prevent negative SEO effects, set up the needed redirects.
DMS changes the structure of RabbitMQ messages. When you’re ready for the migration, wait for all the remaining messages in the queue to be processed. When the queue is empty, enable the maintenance mode. (Expected downtime is limited to the deployment time, normally it takes less than 1hr)
Revert changes in deploy files to disable DMS:

Original environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r dynamic-store --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive --no-ansi -vvv'
SPRYKER_DYNAMIC_STORE_MODE: true
SPRYKER_YVES_HOST_EU: yves.eu.

Updated environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy.dynamic-store-off -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r production.dynamic-store-off --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive.dynamic-store-off --no-ansi -vvv'
SPRYKER_YVES_HOST_DE: de.
SPRYKER_YVES_HOST_AT: at.

Original regions section:

regions:
  broker:
    namespace: eu-docker
  key_value_store:
    namespace: 1
  search:
    namespace: eu_search

Updated regions section:

regions:
  stores:
    DE:
      services:
        broker:
          namespace: de_queue
        key_value_store:
          namespace: 1
        search:
          namespace: de_search
        session:
          namespace: 2
    AT:
      services:
        broker:
          namespace: at_queue
        key_value_store:
          namespace: 3
        search:
          namespace: at_search
        session:
          namespace: 4

Run a normal deploy for your server pipeline.

Verification

- Make sure your store is available at `https://yves.de.mysprykershop.com` or `https://backoffice.de.mysprykershop.com`. - Make sure the store switcher is *not* displayed on the Storefront.

Use AI tools with the AiFoundation module

Wed, 29 Apr 2026 12:02:58 +0000

This document describes how to create and use AI tools with the AiFoundation module to extend AI capabilities by providing custom functions that AI models can invoke during conversations.

Overview

AI tool support enables large language models to call custom functions during conversations. Instead of only generating text, AI models can invoke your application’s functionality, retrieve data, perform calculations, or trigger business logic. This creates more powerful and interactive AI-powered features.

The AI model decides when to call tools based on the conversation context. The Zed facade executes tools with appropriate arguments, receives the results, and incorporates them into the response. The AiFoundation module handles the complete tool execution flow automatically.

Prerequisites

AiFoundation module installed and configured. For details, see AiFoundation module Overview.
Configured AI provider that supports tool calling (OpenAI, Anthropic Claude)

Provider compatibility

Not all AI providers support tool calling. Ensure your configured provider supports this feature. OpenAI and Anthropic Claude have native support for function calling.

Use cases

AI tools are ideal for scenarios where AI needs to interact with your application:

Data retrieval

Enable AI to fetch data from your system:

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameter;

// AI can call this tool to get product information
class GetProductInfoTool implements ToolPluginInterface
{
    public const NAME = 'get_product_info';

    public function getName(): string
    {
        return static::NAME;
    }

    public function getDescription(): string
    {
        return 'Retrieves product information by SKU';
    }

    public function getParameters(): array
    {
        return [
            new ToolParameter(
                name: 'sku',
                type: 'string',
                description: 'The product SKU to retrieve information for',
                isRequired: true
            ),
        ];
    }

    public function execute(...$arguments): mixed
    {
        $sku = $arguments['sku'] ?? null;
        $product = $this->getProductClient()
            ->getProductBySku($sku);

        return json_encode([
            'name' => $product->getName(),
            'price' => $product->getPrice(),
            'availability' => $product->getAvailability(),
        ]);
    }
}

Calculations and processing

Provide specialized calculations:

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameter;

// AI can call this tool to calculate shipping costs
class CalculateShippingTool implements ToolPluginInterface
{
    public const NAME = 'calculate_shipping';

    public function __construct(
        private ShippingCalculatorInterface $shippingCalculator
    ) {
    }

    public function getName(): string
    {
        return static::NAME;
    }

    public function getDescription(): string
    {
        return 'Calculates shipping cost based on weight, destination, and shipping method';
    }

    public function getParameters(): array
    {
        return [
            new ToolParameter(
                name: 'weight',
                type: 'number',
                description: 'Package weight in kilograms',
                isRequired: true
            ),
            new ToolParameter(
                name: 'destination',
                type: 'string',
                description: 'Destination country code (e.g., US, DE, FR)',
                isRequired: true
            ),
            new ToolParameter(
                name: 'method',
                type: 'string',
                description: 'Shipping method: standard, express, or overnight',
                isRequired: false
            ),
        ];
    }

    public function execute(...$arguments): mixed
    {
        $weight = $arguments['weight'] ?? 0;
        $destination = $arguments['destination'] ?? '';
        $method = $arguments['method'] ?? 'standard';

        $cost = $this->shippingCalculator
            ->calculate($weight, $destination, $method);

        return (string) $cost;
    }
}

Business logic execution

Allow AI to trigger business operations:

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameter;

// AI can call this tool to create support tickets
class CreateSupportTicketTool implements ToolPluginInterface
{
    public const NAME = 'create_support_ticket';

    public function __construct(
        private SupportFacadeInterface $supportFacade
    ) {
    }

    public function getName(): string
    {
        return static::NAME;
    }

    public function getDescription(): string
    {
        return 'Creates a support ticket with title, description, and priority';
    }

    public function getParameters(): array
    {
        return [
            new ToolParameter(
                name: 'title',
                type: 'string',
                description: 'Brief title summarizing the issue',
                isRequired: true
            ),
            new ToolParameter(
                name: 'description',
                type: 'string',
                description: 'Detailed description of the issue or request',
                isRequired: true
            ),
            new ToolParameter(
                name: 'priority',
                type: 'string',
                description: 'Priority level: high, medium, or low',
                isRequired: false
            ),
        ];
    }

    public function execute(...$arguments): mixed
    {
        $title = $arguments['title'] ?? '';
        $description = $arguments['description'] ?? '';
        $priority = $arguments['priority'] ?? 'medium';

        $ticketId = $this->supportFacade
            ->createTicket($title, $description, $priority);

        return sprintf('Ticket created with ID: %s', $ticketId);
    }
}

Create tool sets

Tool sets group related tools together. Create a tool set class that implements ToolSetPluginInterface. Tool sets are Zed-layer plugins registered in the Zed AiFoundationDependencyProvider.

<?php

namespace Pyz\Zed\YourModule\Communication\Plugin\AiFoundation;

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolSetPluginInterface;

class CustomerServiceToolSet implements ToolSetPluginInterface
{
    public const NAME = 'customer_service_tools';

    public function getName(): string
    {
        return static::NAME;
    }

    public function getTools(): array
    {
        return [
            new GetOrderStatusTool(),
            new CreateRefundTool(),
            new UpdateCustomerAddressTool(),
            new SendNotificationTool(),
        ];
    }
}

Organizing tools into sets

Group tools by functional domain:

// Product-related tools
class ProductToolSet implements ToolSetPluginInterface
{
    public const NAME = 'product_tools';

    public function getName(): string
    {
        return static::NAME;
    }

    public function getTools(): array
    {
        return [
            new SearchProductsTool(),
            new GetProductDetailsTool(),
            new CheckStockTool(),
        ];
    }
}

// Order-related tools
class OrderToolSet implements ToolSetPluginInterface
{
    public const NAME = 'order_tools';

    public function getName(): string
    {
        return static::NAME;
    }

    public function getTools(): array
    {
        return [
            new CreateOrderTool(),
            new GetOrderHistoryTool(),
            new CancelOrderTool(),
        ];
    }
}

Register tool sets

<?php

namespace Pyz\Zed\AiFoundation;

use Pyz\Zed\YourModule\Plugin\AiFoundation\CustomerServiceToolSet;
use Pyz\Zed\YourModule\Plugin\AiFoundation\ProductToolSet;
use Pyz\Zed\YourModule\Plugin\AiFoundation\OrderToolSet;
use Spryker\Zed\AiFoundation\AiFoundationDependencyProvider as SprykerAiFoundationDependencyProvider;

class AiFoundationDependencyProvider extends SprykerAiFoundationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Tools\ToolSetPluginInterface>
     */
    protected function getAiToolSetPlugins(): array
    {
        return [
            new CustomerServiceToolSet(),
            new ProductToolSet(),
            new OrderToolSet(),
        ];
    }
}

Use tools in AI requests

Specify which tool sets to make available to the AI by adding tool set names to your prompt request:

<?php

namespace Pyz\Zed\YourModule\Business\Assistant;

use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Pyz\Zed\YourModule\Plugin\AiFoundation\CustomerServiceToolSet;
use Pyz\Zed\YourModule\Plugin\AiFoundation\OrderToolSet;
use Spryker\Zed\AiFoundation\Business\AiFoundationFacadeInterface;

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

    public function handleCustomerInquiry(string $customerMessage): string
    {
        $promptRequest = (new PromptRequestTransfer())
            ->setAiConfigurationName('openai')
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent($customerMessage)
            )
            ->addToolSetName(CustomerServiceToolSet::NAME)
            ->addToolSetName(OrderToolSet::NAME)
            ->setMaxRetries(2);

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

        if ($promptResponse->getIsSuccessful() !== true) {
            return 'I apologize, but I encountered an error processing your request.';
        }

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

The AI model has access to all tools from all specified tool sets.

Example: Support ticket creation via AI

Here is a complete example showing how the AI can automatically create support tickets using the CreateSupportTicketTool:

<?php

namespace Pyz\Zed\YourModule\Business;

use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Pyz\Zed\YourModule\Plugin\AiFoundation\CustomerServiceToolSet;
use Spryker\Zed\AiFoundation\Business\AiFoundationFacadeInterface;

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

    public function processCustomerMessage(string $customerMessage): void
    {
        // Request AI to process the message with access to support tools
        $promptRequest = (new PromptRequestTransfer())
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent($customerMessage)
            )
            ->addToolSetName(CustomerServiceToolSet::NAME) // Includes CreateSupportTicketTool
            ->setMaxRetries(2);

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

        if ($promptResponse->getIsSuccessful() !== true) {
            throw new Exception('Failed to process customer message');
        }

        // Check if the AI invoked the create support ticket tool
        foreach ($promptResponse->getToolInvocations() as $toolInvocation) {
            if ($toolInvocation->getName() === 'create_support_ticket') {
                $ticketId = $toolInvocation->getResult();
                echo sprintf('Support ticket created: %s', $ticketId);
            }
        }

        // Send the AI response to the customer
        $response = $promptResponse->getMessage()->getContent();
        echo $response;
    }
}

In this example, when the customer sends a message like “I need to report a critical bug”, the AI can:

Understand the customer’s intent
Extract the ticket title, description, and priority
Invoke the create_support_ticket tool through the facade
Receive the ticket ID from the tool result
Incorporate the ticket information into its response to the customer

Handle tool call results

Tool calls are automatically executed and their results are included in the response:

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

if ($promptResponse->getIsSuccessful() === true) {
    // Get the final AI response
    $finalMessage = $promptResponse->getMessage()->getContent();

    // Access tool invocation information
    foreach ($promptResponse->getToolInvocations() as $toolInvocation) {
        $toolName = $toolInvocation->getName();
        $toolArguments = $toolInvocation->getArguments();
        $toolResult = $toolInvocation->getResult();

        // content and reasoning are populated when the provider returns them alongside the tool call
        $content = $toolInvocation->getContent();   // e.g. "I will search for that now."
        $reasoning = $toolInvocation->getReasoning(); // chain-of-thought, when available

        // Log or process tool invocations
        $this->logger->info(sprintf(
            'AI invoked tool "%s" with arguments: %s. Result: %s',
            $toolName,
            json_encode($toolArguments),
            $toolResult
        ));
    }
}

Tool call flow

The complete flow when tools are used:

AI receives the prompt and available tools
AI decides to call one or more tools
AiFoundation automatically executes the tools with provided arguments
Tool results are sent back to the AI
AI incorporates results and may call additional tools
Process continues until AI provides final response
Final response and all tool invocations are returned in ToolInvocationTransfer objects

Best practices

Provide clear tool descriptions

Write descriptions that help the AI understand when and how to use tools:

// Good: Clear, specific description
public function getDescription(): string
{
    return 'Searches for products by name, category, or SKU. Returns product name, price, and availability status.';
}

// Avoid: Vague description
public function getDescription(): string
{
    return 'Product search';
}

Design focused tools

Create tools with single, well-defined purposes:

// Good: Focused tool
class GetOrderStatusTool implements ToolPluginInterface
{
    public const NAME = 'get_order_status';

    public function getName(): string
    {
        return static::NAME;
    }
}

// Avoid: Tool that does too much
class ManageOrdersTool implements ToolPluginInterface
{
    public function execute(...$arguments): mixed
    {
        $action = $arguments['action']; // create, update, cancel, status...
        // Too many responsibilities
    }
}

Return structured data

Return JSON-encoded data for complex results:

public function execute(...$arguments): mixed
{
    $order = $this->getOrderDetails($arguments['order_id']);

    return json_encode([
        'order_id' => $order->getOrderId(),
        'status' => $order->getStatus(),
        'total' => $order->getTotal(),
        'items' => $order->getItems(),
        'created_at' => $order->getCreatedAt(),
    ]);
}

Validate tool arguments

Always validate arguments before execution:

public function execute(...$arguments): mixed
{
    $orderId = $arguments['order_id'] ?? null;

    if ($orderId === null || !is_string($orderId)) {
        return json_encode([
            'error' => 'Invalid order_id parameter',
        ]);
    }

    // Proceed with execution
}

Handle errors gracefully

Return error information in a consistent format:

public function execute(...$arguments): mixed
{
    try {
        $result = $this->performOperation($arguments);

        return json_encode([
            'success' => true,
            'data' => $result,
        ]);
    } catch (\Exception $e) {
        return json_encode([
            'success' => false,
            'error' => $e->getMessage(),
            'error_code' => $e->getCode(),
        ]);
    }
}

Security considerations

Validate permissions. Always check user permissions before executing sensitive operations;
Sanitize inputs. Sanitize all inputs before using them in queries or operations;

Limitations

Provider-specific constraints

Different AI providers have varying limitations:

Maximum number of tools per request
Maximum tool description length
Supported parameter types
Tool execution timeout limits

Performance considerations

Tool execution adds latency to AI requests:

Each tool call requires additional round-trip to the AI provider
Complex tools may take time to execute
Multiple sequential tool calls increase total response time

Consider these factors when designing time-sensitive features.

Token usage

Tool definitions and results consume tokens from your AI provider quota. Monitor token consumption when using tools extensively.

Conversation History

Wed, 29 Apr 2026 12:02:58 +0000

This document describes how to use conversation history with the AiFoundation module to maintain conversation context across multiple interactions, enabling multi-turn conversations where the AI can reference previous messages and provide contextually relevant responses.

Conversation history is persisted in the database using the spy_ai_conversation_history table, ensuring conversations are stored durably and can be retrieved at any time.

Overview

Conversation history enables you to maintain persistent conversation context across multiple interactions. Instead of sending isolated prompts, you can build conversational experiences where the AI remembers previous messages and maintains state throughout an extended dialogue.

The conversation history feature automatically persists all messages in a conversation to the database. When you include a conversation reference in your prompt request, all exchanges are stored in the spy_ai_conversation_history table and automatically included in subsequent requests to maintain context.

Prerequisites

AiFoundation module installed and configured. For details, see AiFoundation module Overview.
Database configured and migrated to include the spy_ai_conversation_history table

Key concepts

Conversation Reference

A unique identifier for a conversation. All messages in a conversation are stored together under this reference. You can use any string as a conversation reference, such as a customer ID, session ID, or custom identifier.

Context window

The maximum number of tokens that can be stored in a conversation. Default is 50000 tokens. When a conversation exceeds this limit, the oldest messages are automatically pruned to maintain the window size.

Configure conversation history

Configure the context window for conversation history in your AI configuration.

Default configuration

Update your config/Shared/config_ai.php:

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

$config[AiFoundationConstants::CONVERSATION_HISTORY_CONTEXT_WINDOW] = 50000; // tokens

Per-AI-configuration settings

Configure the context window for specific AI configurations by adding conversation_history settings within AI_CONFIGURATIONS:

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

$config[AiFoundationConstants::AI_CONFIGURATIONS] = [
    'customer_support' => [
        'provider_name' => AiFoundationConstants::PROVIDER_OPENAI,
        'provider_config' => [
            'api_key' => getenv('OPENAI_API_KEY'),
            'model' => 'gpt-4',
        ],
        'system_prompt' => 'You are a helpful customer support assistant.',
        'conversation_history' => [
            'context_window' => 100000, // Larger context for complex support cases
        ],
    ],
];

Per-configuration settings take precedence over global defaults. If conversation_history is not specified for an AI configuration, it falls back to the global CONVERSATION_HISTORY_CONTEXT_WINDOW value.

Best practice

Adjust context window based on expected conversation length and token limits of your AI provider. Large context windows provide better conversation history but require more tokens for each AI request.

Use conversation history in conversations

Basic multi-turn conversation

To enable conversation history, include a conversationReference in your PromptRequestTransfer. All messages are automatically persisted and included in future requests:

<?php

namespace Pyz\Zed\YourModule\Business;

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

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

    public function respondToCustomer(string $conversationReference, string $userMessage): string
    {
        // Create a new prompt request with conversation reference
        $promptRequest = (new PromptRequestTransfer())
            ->setConversationReference($conversationReference) // Enable conversation history
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent($userMessage)
            );

        // The AI automatically has access to conversation history
        $response = $this->aiFoundationFacade->prompt($promptRequest);

        if ($response->getIsSuccessful() === true) {
            return $response->getMessage()->getContent();
        }

        return 'An error occurred processing your request.';
    }
}

Manage conversation history

Access the complete conversation history at any time:

<?php

namespace Pyz\Zed\YourModule\Business;

use Generated\Shared\Transfer\ConversationHistoryCriteriaTransfer;
use Generated\Shared\Transfer\ConversationHistoryConditionsTransfer;
use Spryker\Zed\AiFoundation\Business\AiFoundationFacadeInterface;

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

    public function getConversationMessages(string $conversationReference): array
    {
        $conversationHistoryCriteriaTransfer = (new ConversationHistoryCriteriaTransfer())
            ->setConversationHistoryConditions(
                (new ConversationHistoryConditionsTransfer())
                    ->setConversationReferences([$conversationReference])
            );

        $conversationHistoryCollectionTransfer = $this->aiFoundationFacade->getConversationHistoryCollection($conversationHistoryCriteriaTransfer);
        $conversationHistories = $conversationHistoryCollectionTransfer->getConversationHistories();

        if ($conversationHistories->count() === 0) {
            return [];
        }

        $conversationHistoryTransfer = $conversationHistories->offsetGet(0);
        $messages = $conversationHistoryTransfer->getMessages();

        $formattedMessages = [];
        foreach ($messages as $message) {
            $formattedMessages[] = [
                'type' => $message->getType(), // 'user', 'assistant', 'tool_call', 'tool_result'
                'content' => $message->getContent(),
                'reasoning' => $message->getReasoning(), // null when provider does not return reasoning
            ];
        }

        return $formattedMessages;
    }

    public function getMultipleConversations(array $conversationReferences): array
    {
        $conversationHistoryCriteriaTransfer = (new ConversationHistoryCriteriaTransfer())
            ->setConversationHistoryConditions(
                (new ConversationHistoryConditionsTransfer())
                    ->setConversationReferences($conversationReferences)
            );

        $conversationHistoryCollectionTransfer = $this->aiFoundationFacade->getConversationHistoryCollection($conversationHistoryCriteriaTransfer);
        $conversationHistories = $conversationHistoryCollectionTransfer->getConversationHistories();

        $result = [];
        foreach ($conversationHistories as $conversationHistory) {
            $result[$conversationHistory->getConversationReference()] = [
                'conversation_reference' => $conversationHistory->getConversationReference(),
                'message_count' => $conversationHistory->getMessages()->count(),
                'messages' => array_map(function ($message) {
                    return [
                        'type' => $message->getType(),
                        'content' => $message->getContent(),
                    ];
                }, $conversationHistory->getMessages()->getArrayCopy()),
            ];
        }

        return $result;
    }
}

API reference

AiFoundationFacade

prompt()

Sends a message in a conversation. If conversationReference is provided, the message is stored in conversation history and previous messages are automatically included in the AI’s context.

/**
 * @param \Generated\Shared\Transfer\PromptRequestTransfer $promptRequest
 * @return \Generated\Shared\Transfer\PromptResponseTransfer
 */
public function prompt(PromptRequestTransfer $promptRequest): PromptResponseTransfer

PromptRequestTransfer properties for conversation history:

conversationReference (string, optional): Enable conversation history by providing a unique conversation identifier
aiConfigurationName (string, optional): Configuration name to use, defaults to AI_CONFIGURATION_DEFAULT
promptMessage (PromptMessageTransfer, required): The message to send
maxRetries (int, optional): Number of retry attempts on failure

getConversationHistoryCollection()

Retrieves conversation history collection based on criteria. Allows filtering conversations by conversation IDs.

/**
 * @param \Generated\Shared\Transfer\ConversationHistoryCriteriaTransfer $conversationHistoryCriteriaTransfer
 * @return \Generated\Shared\Transfer\ConversationHistoryCollectionTransfer
 */
public function getConversationHistoryCollection(
    ConversationHistoryCriteriaTransfer $conversationHistoryCriteriaTransfer
): ConversationHistoryCollectionTransfer

ConversationHistoryCriteriaTransfer properties:

conversationHistoryConditions (ConversationHistoryConditionsTransfer): Filter conditions for the query
- conversationReferences (string[]): List of conversation references to retrieve (IN operation). If empty, returns empty collection.

Returns: ConversationHistoryCollectionTransfer containing:

conversationHistories (ConversationHistoryTransfer[]): Array of conversation histories matching the criteria
- Each ConversationHistoryTransfer contains:
  - conversationReference (string): The conversation reference
  - messages (PromptMessageTransfer[]): Array of all messages in the conversation with types (user, assistant, tool_call, tool_result), content, reasoning, and attachments

Message types

Messages stored in conversation history have different types:

user - Message sent by the user
assistant - Response from the AI
tool_call - A tool invocation initiated by the AI
tool_result - Result of a tool execution

Tool-related types are only present when using AI tools with conversation history.

Best practices

1. Use meaningful conversation references

Choose conversation references that align with your business logic:

// Good: Clear relationship to entity
$conversationReference = "customer_conversation_{$customerId}_{$timestamp}";
$conversationReference = "support_ticket_{$ticketId}";

// Avoid: Generic IDs that are hard to track
$conversationReference = "conv_123";

2. Manage conversation cleanup

Implement your own cleanup strategy for old conversations if needed. Unlike Redis-backed storage with automatic expiration, database-persisted conversations remain indefinitely. Consider creating a scheduled task to delete conversations older than a certain date if storage management is important.

3. Handle large conversations

Monitor context window usage. If approaching limits, start a new conversation.

4. Secure conversation access

Validate that users can only access their own conversations by filtering conversation references based on user permissions:

$conversationHistoryCriteriaTransfer = (new ConversationHistoryCriteriaTransfer())
    ->setConversationHistoryConditions(
        (new ConversationHistoryConditionsTransfer())
            ->setConversationReferences($userAuthorizedConversationReferences) // Only user's conversations
    );

$conversationHistoryCollectionTransfer = $this->aiFoundationFacade->getConversationHistoryCollection($conversationHistoryCriteriaTransfer);

Limitations

Conversation history is stored in the database and requires the spy_ai_conversation_history table to be present
Conversations persist indefinitely in the database; implement your own cleanup strategy if needed
Very large conversations may approach the context window limit, requiring new conversation references
Tool invocations and results are included in history and count toward context window

Debugging

Conversation history messages are persisted in the spy_ai_conversation_history database table. You can query the database directly to inspect stored conversations and messages for debugging purposes.

Packaged Business Capabilities

Wed, 29 Apr 2026 10:34:52 +0000

Packaged Business Capabilities (PBCs) are capabilities that enclose a certain functionality with the Spryker system. PBCs provide a good foundation for decision makers throughout multiple business entities. This section is in beta because not all the PBCs are covered. Marketplace functionalities will also be added at a later stage. You are welcome to use the docs that are already here, and we will keep adding the docs for the rest of the PBCs. ## Spryker PBCs | NAME | DESCRIPTION | BENEFITS | | --- | --- | --- | | [AI Foundation](/docs/pbc/all/ai-foundation/{{site.version}}/ai-foundation.html) | Provider agnostic AI layer that connects Spryker Commerce OS to leading AI providers through one common interface. | Accelerates delivery of AI features and keeps freedom to choose and change AI providers and models per use case. | | [AI Commerce](/docs/pbc/all/ai-commerce/{{site.version}}/ai-commerce.html) | Brings AI assisted capabilities to the Spryker storefront and Backoffice to help buyers and operators complete commerce tasks faster and more consistently, reducing manual effort with human review and enterprise governance. | Speeds up key commerce workflows while improving consistency and reducing errors, enabling scalable adoption of assisted capabilities across teams and markets. | | [Business Intelligence](/docs/pbc/all/business-intelligence/{{site.version}}/business-intelligence.html) | Analyze data to understand how your shop performs and areas for improvement. | Make informed decisions. | | [Carrier Management](/docs/pbc/all/carrier-management/{{site.version}}/carrier-management.html) | The Spryker Cloud Commerce OS integrates with several shipping carriers and methods and lets you define their availability, price, and tax set. During the checkout process, customers have the option to select their preferred shipment method and relevant carrier. | Ensures quick and cost-effective delivery. | | [Cart and Checkout](/docs/pbc/all/cart-and-checkout/{{site.version}}/cart-and-checkout.html) | The online shopping cart and checkout process act as a gateway for customer and order management. It lets your customers organize and manage their purchases, apply vouchers and coupon codes. Based on their roles and permissions, your B2B customers can add or remove products, share the cart, and manage their purchases. | Increases conversion rates and reduces drop-off rates. Offers additional B2B specific, permission-related functionalities. | | [Content Management System (CMS)](/docs/pbc/all/content-management-system/{{site.version}}/content-management-system.html) | The CMS features let you customize your store, enrich it with information, stories, or other content, and make it easily findable in search engines. Several SEO features enable you to add customized meta information to all your content and create search engine-friendly URLs. | Provides compelling content and stories where your customers need it. | | [Customer Relationship Management (CRM)](/docs/pbc/all/customer-relationship-management/{{site.version}}/customer-relationship-management.html) | The customer management tool lets B2B and B2C businesses manage customer accounts and efficiently monitor shopping habits. It provides your B2B Customers with a way to map their business hierarchies, permissions, and role management. With the creation of distinctive Business Units, the internal hierarchy can easily be mapped out, and each Unit can operate independently. The Roles and Permissions System lets your customer's buyers define the purchase and approval process. | Increases conversion rates and average order values with a compact Customer Relationship Management tool. | | [Data Exchange](/docs/pbc/all/data-exchange/{{site.version}}/data-exchange.html) | You can import your business logic and data, including product information, customer base, categories, and more, into the Spryker Cloud Commerce OS. You can use the out-of-the-box export data functionality as a generic blueprint for any data set that you need to export. | Lets you import and export specific data points quickly and easily. | | [Discount Management](/docs/pbc/all/discount-management/{{site.version}}/discount-management.html) | You can define several types of discounts based on a brand, the overall cart value, specific product ranges, or unique customer groups. You can also offer discount vouchers or incentivize certain products through coupon codes. | Lets you run effective promotional campaigns to boost conversion rates. | | [Dynamic Multistore](/docs/pbc/all/dynamic-multistore/{{site.version}}/dynamic-multistore.html) | Manage stores in the Back Office | Make changes to your stores setup quickly and easily. | | [Emails](/docs/pbc/all/emails/{{site.version}}/emails.html) | You can send automated account e-mails and confirmations or offer different types of newsletter subscriptions. | Keep in touch with your customers. | | [Gift Cards](/docs/pbc/all/gift-cards/{{site.version}}/gift-cards.html) | Lets your customers purchase and redeem gift cards. Enabling gift card purchases can boost your brand awareness and help you reach new customers. | Lets you acquire new customers through gift card payment options. | | [Identity Access Management (IAM)](/docs/pbc/all/identity-access-management/{{site.version}}/identity-access-management.html) | Enables the creation of new accounts for end customers and B2B customers. It also allows users to define password settings and utilize multi-login blockers for security purposes. Moreover, a third-party access management function is integrated. | Allows for quick and easy authorization and authentication of customers | | [Merchant Management](/docs/pbc/all/merchant-management/{{site.version}}/merchant-management.html) | For efficient Merchant Management, two parts are important. One, the overview and management on the Operator side, like approvals, edits, etc. And two, the self-service management of the Merchants, where they can take care of their daily business, like order or product management. | Gives you an overview of all your Merchants' activities. | | Miscellaneous | This category holds the documents that are not related to any PBC. | | | [Offer Management](/docs/pbc/all/offer-management/{{site.version}}/offer-management.html) | Lets your Merchants create Offers on existing products in your Marketplace. By doing so, duplicates in the product catalog can be avoided and the management of Merchants, Products, and Offers becomes much more convenient. | Saves time because of a good overview of Merchant's Offers. | | [Order Management System (OMS)](/docs/pbc/all/order-management-system/{{site.version}}/order-management-system.html) | Helps you keep track of your order processing from your B2B, B2C, or Marketplace, and ensure quick fulfillment. You can manage incoming orders in the Back Office, view and edit orders, track their progress, or contact customers who make open orders directly. With the compact Order Management features, you can keep your order processing running smoothly. | Lets you pProcess orders smoothly to fulfill them quickly. | | [Payment Service Provider (PSP)](/docs/pbc/all/payment-service-provider/{{site.version}}/payment-service-provider.html) | Provides integration of payment methods. You can integrate multiple payment gateways, define their availability, and customize how they appear on your site. | Lets you provide an excellent shopping experience and integrate your customers' preferred payment methods. | | [Price Management](/docs/pbc/all/price-management/{{site.version}}/price-management.html) | The Spryker Cloud Commerce OS supports multiple currencies and automatically detects the payment currency based on a customer's preference. You can manage gross and net prices per product and per country. You can also offer volume discounts to encourage customers to purchase products in larger quantities. | Saves you time by letting you implement your pricing strategy in one place and catering it to your business needs. | | [Product Information Management (PIM)](/docs/pbc/all/product-information-management/{{site.version}}/product-information-management.html) | Encompasses all functionality that is needed to set up your product catalog. With PIM, you can create and extend the product catalog to match your business needs. | Helps you expand your business by organizing your products in a fast and efficient way. | | [Product Relationship Management](/docs/pbc/all/product-relationship-management/{{site.version}}/product-relationship-management.html) | Helps you enhance your shop with cross- and up-selling capabilities to increase sales. | Increases average order values with product relations. | | [Ratings and Reviews](/docs/pbc/all/ratings-reviews/{{site.version}}/ratings-and-reviews.html) | Lets you incorporate user reviews and ratings. You can receive and moderate feedback in the Back Office. The Ratings and Reviews feature also comes with the functionality to add text-free reviews and star ratings. | Inspires trust among customers with ratings and reviews. | | [Request for Quote (RFQ)](/docs/pbc/all/request-for-quote/{{site.version}}/request-for-quote.html) | Your customers can request a quote for products and services that you sell. The Request for Quote feature supports all functionalities of the price engine and product capabilities, such as Volume Prices, Customer Specific Prices, Measuring and Packaging units, Shipping costs, Product Options, etc. | Enhances customer loyalty and increase conversion rates. | | [Return Management](/docs/pbc/all/return-management/{{site.version}}/marketplace/marketplace-return-management-feature-overview.html) | Lets you establish a return policy and execute returns. | Increase customer satisfaction and loyalty. | | [Search](/docs/pbc/all/search/{{site.version}}/base-shop/search-feature-overview/search-feature-overview.html) | The out-of-the-box Elasticsearch technology lets you include full-text search, auto-suggestions, and auto-completion. You can set individual search preferences for multiple stores and categorize your products by adding dynamic filters and facets to help your customers further refine the search results. You can also add more advanced filters that use the product's metadata or promote a brand's top-sellers or highly rated products. | Helps you increase conversion rates by providing an excellent Search and Filter experience. | | [Service Points Management](/docs/pbc/all/service-point-management/{{site.version}}/service-point-management.html) | Set up offline service points where customers can interact with your business. | Creates touch points to connect a shop with offline locations. | | [Shopping List and Wishlist](/docs/pbc/all/shopping-list-and-wishlist/{{site.version}}/shopping-list-and-wishlist.html) | Your B2B customers can save the products they wish to purchase, in shopping lists. Different roles and permission systems ensure smooth sharing and contribution management amongst company users. This PBC encompasses additional features like printing, barcode generation, and direct-to-cart. Enabling your B2C customers to track and save the products they wish to purchase through a wish list function effectively reduces cart abandonment, boosts your sales, and allows you to keep track of which products are of interest to your customers. | Lets you increase conversion rates and loyalty by offering rich Shopping and B2B Wish Lists. | | [Tax Management](/docs/pbc/all/tax-management/{{site.version}}/tax-management.html) | Lets you adhere to respective tax regulations in the countries you sell by configuring and managing tax rates for products, shipments, and additional services. You can define tax rates for different countries and apply integrations to manage US taxes. | Lets you comply with fiscal regulations. | | [User Management](/docs/pbc/all/user-management/{{site.version}}/user-management.html) | Lets the Back Office users manage user access, set rights, and onboard customers. | Ensures high security and compliance through managed user flows. | | [Warehouse Management System (WMS)](/docs/pbc/all/warehouse-management-system/{{site.version}}/warehouse-management-system.html) | Lets you keep an overview of your stock levels in the Back Office to determine accurate availabilities on your store's website. Any open orders or reserved items are taken into consideration when stock availabilities are displayed. | Helps you save your time by keeping an eye on your stock levels. | ### Application PBCs | NAME | DESCRIPTION | BENEFITS | | --- | --- | --- | | Back Office | The administration interface that allows you to manage all back-office tasks. In the Back Office, you can manage and create customer accounts and define who can access the Back Office. You can also keep track of all your internal processes including the management of your products, orders, customers and many more. | Keeps your back-end processes running efficiently, protects your data and administers all accounts. | | Storefront | The out-of-the-box online shop application that includes all regular functionalities and workflows. You can use the Storefront as a boilerplate to kick-start your project. | Lets you easily start your online shop from our boilerplate solution. | ## App Composition Platform apps

| APP | CATEGORY | | --- | --- | | [Vertex](/docs/pbc/all/tax-management/{{site.version}}/base-shop/third-party-integrations/vertex/vertex.html) | Tax compliance. | | [Algolia](/docs/pbc/all/search/{{site.version}}/base-shop/third-party-integrations/algolia/integrate-algolia.html) | Search engine. | | [Payone](/docs/pbc/all/payment-service-providers/payone/integrate-payone.html) | Payment service provider. | | [Bazaarvoice](/docs/pbc/all/ratings-reviews/{{site.version}}/third-party-integrations/integrate-bazaarvoice.html) | Platform for user-generated content. | | [Stripe](/docs/pbc/all/payment-service-provider/{{site.version}}/base-shop/third-party-integrations/stripe/stripe.html) | Financial infrastructure platform. |

AI Commerce

Wed, 29 Apr 2026 10:34:52 +0000

AI Commerce brings AI-powered capabilities to your Spryker storefront and back office, reducing manual effort for buyers and shop operators, accelerating commerce workflows. Features are built on the AiFoundation abstraction layer, so the underlying AI model can be swapped or configured per feature without changing application code.

Features

FEATURE	DESCRIPTION
Smart PIM	Help catalog managers enrich product information directly in the Backoffice PIM. Get guided suggestions to speed up day-to-day catalog work, improve consistency across markets and languages, and keep full control through human review and auditability.
Visual Add to Cart	Lets buyers upload a product image on the Quick Order page. AI recognizes the products in the image and pre-fills the order form with matching SKUs and quantities — enabling rapid bulk ordering without manual entry.
Back Office Assistant	An AI-powered chat widget embedded in the Back Office. Admin users can ask natural language questions to navigate the Back Office, diagnose order issues, and create or update discounts.
Search by Image	Lets customers upload a photo to search for products. AI analyzes the image, identifies a search term, and redirects to search results or the first matching product page.

Who benefits

ROLE	BENEFIT
B2B buyers	Faster reordering from photos of shelves, product lists, or packaging. Find products by uploading a photo instead of searching by name.
Store operators	Reduced support requests caused by manual order entry errors. Faster Back Office workflows through conversational AI assistance.
Developers	AI provider-agnostic integration — swap or configure models per feature via configuration.

Spryker Documentation

Resource Schemas

Migration status - Glue API to API Platform

AiFoundation module Overview

Architecture

Install the AiFoundation module

Configure AI providers

Configuration structure

Default configuration

Provider configuration examples

OpenAI

Anthropic Claude

AWS Bedrock

Ollama (local/self-hosted)

Run Ollama with Docker SDK

Google Gemini

Deepseek

HuggingFace

Mistral AI

xAI Grok

Azure OpenAI

Use the AiFoundation facade

Basic usage

Using a specific configuration

Multiple configurations example

Available provider constants

Transfer objects

PromptRequest

PromptMessage

PromptResponse

Attachment

ToolInvocation

StructuredMessage

Conversation History

About NeuronAI framework

Install the Product Attribute Visibility feature

Release notes 202604.0

Enable Dynamic Multistore

Prerequisites

Enable Dynamic Multistore

Check if Dynamic Multistore is enabled

Disable Dynamic Multistore

Use AI tools with the AiFoundation module

Overview

Prerequisites

Use cases

Data retrieval

Calculations and processing

Business logic execution

Create tool sets

Organizing tools into sets

Register tool sets

Use tools in AI requests

Example: Support ticket creation via AI

Handle tool call results

Tool call flow

Best practices

Provide clear tool descriptions

Design focused tools

Return structured data

Validate tool arguments

Handle errors gracefully

Security considerations

Limitations

Provider-specific constraints

Performance considerations

Token usage

Related documentation

Conversation History

Overview

Prerequisites

Key concepts

Conversation Reference

Context window

Configure conversation history

Default configuration

Per-AI-configuration settings

Use conversation history in conversations

Basic multi-turn conversation

Manage conversation history