Spryker Documentation

Create discounts

Tue, 15 Sep 2026 14:49:42 +0000

This document describes how to create discounts in the Back Office.

Prerequisites

If you are new to discounts, you might want to start with Best practices: Promote products with discounts.

There is a reference information for each section. Review it before you start, or look up the necessary information as you go through the process.

To create a discount, do the following:

Go to Merchandising > Discount.
On the Discount page, click Create new discount.

1. Define general settings of the discount

On the Create Discount page, click the General information tab.
For STORE RELATION, select one or more stores you want the discount to be displayed in.
Select a DISCOUNT TYPE.
Enter a NAME.
Optional: Enter a DESCRIPTION.
Optional: Enter a PRIORITY.
Optional: To make the discount exclusive, select EXCLUSIVE.
Select a VALID FROM date.
Select a VALID TO date.
Click Next.

2. Define discount calculation and the products to apply the discount to

Click the Discount calculation tab.
Select a CALCULATOR TYPE.
Based on the calculator type you’ve selected, do one of the following:
- Fixed amount: Enter the needed discounted prices.
- Percentage: For VALUE, enter a percentage to be discounted.
Select a DISCOUNT APPLICATION TYPE.
Depending on the discount application type you’ve selected, do the following:
- QUERY STRING: Add a query using the query builder or by entering a plain query.
- PROMOTIONAL PRODUCT:
  1. Enter ABSTRACT PRODUCT SKU.
  2. Enter a QUANTITY.
Click Next.

3. Define on what conditions the discount can be applied

Click the Conditions tab.
For APPLY WHEN, add a query using the query builder or by entering a plain query.
For THE DISCOUNT CAN BE APPLIED IF THE QUERY APPLIES FOR AT LEAST X ITEM(S)., enter a number.
Click Save.

This refreshes the page with a success message displayed.

4. Generate voucher codes

If you are creating a cart rule, proceed to step 5. Activate the discount

Click the Voucher codes tab.
Enter a QUANTITY.
Optional: Enter a CUSTOM CODE.
Optional: For ADD RANDOM GENERATED CODE LENGTH, select a number.
Enter a MAX NUMBER OF USES.
Click Generate. This refreshes the page with a success message displayed. The created voucher codes are displayed in the Generated Discount Codes section.

5. Activate the discount

Optional: To make the discount redeemable on the Storefront, click Activate in the top-right corner.

This refreshes the page with a success message displayed.

Reference information: Define general settings of the discount

ATTRIBUTE	DESCRIPTION
STORE RELATION	The stores to display the discount in.
DISCOUNT TYPE	Defines how the discount is applied: Cart rule: the discount is applied automatically to the products defined in Define discount calculation and the products to apply the discount to. Voucher codes: the discount is applied to the products defined in Define discount calculation and the products to apply the discount to when a customer enters a voucher code generated in Generate voucher codes.
NAME	The unique ID of the discount that is displayed in the Back Office and on the Storefront.
DESCRIPTION	The description is displayed only in the Back Office.
PRIORITY	Defines the order of discounts being applied. Accepts integers from `1` to `9999` with `1` being the highest priority.
NON-EXCLUSIVE	Defines that this discount can be applied to a cart together with other non-exclusive discounts.
EXCLUSIVE	Defines that this discount, when applied to a cart, discards all non-exclusive discounts. If multiple exclusive discounts are applied to a cart, only the discount with the bigger discount value is applied.
VALID FROM and VALID TO	Inclusively, define the dates between which the discount can be applied.

Reference information: Define discount calculation and the products to apply the discount to

This section contains information for defining discount calculation and the product to apply the discount to.

CALCULATOR TYPE

The discount can be calculated in two ways:

Percentage: The discount is calculated as a percentage of the discounted items.
Fixed amount: A fixed amount is discounted.

Example:

PRODUCT PRICE	CALCULATOR TYPE	AMOUNT	DISCOUNT APPLIED	PRICE TO PAY
50 €	Percentage	10	5 €	45 €
50 €	Fixed amount	10 €	10 €	40 €

DISCOUNT APPLICATION TYPE: QUERY STRING

A query string defines what products a discount applies to. A query string consists of decision rules. Only the products that fulfill all the decision rules are discountable. You can define a query string by entering a plain query or by using a query builder.

Query builder:

Plain query:

A decision rule consists of the following:

Attribute. For example, attribute.color. Attribute fields are named attribute.<attribute_key> and are generated from the product attribute keys that exist in your database. If an attribute key does not exist in your database, the corresponding field is not offered. To add attribute keys, see Create product attributes.
Relation operator. For example, equal.
Value. For example, black.

You can find query examples in the following table.

PLAIN QUERY	EXPLANATION
day-of-week = ‘1’	Discount applies to any orders that are placed on Monday.
shipment-carrier != ‘1’ AND price-mode = ‘GROSS_MODE’	Discount applies if the shipment carrier with the identifier `1` is not chosen, and if gross pricing is selected.
currency != ‘EUR’ OR price-mode = ‘GROSS_MODE’	Discount applies if the selected currency is not the Euro, or if the pricing mode is gross.

DISCOUNT APPLICATION TYPE: PROMOTIONAL PRODUCT

The promotional product lets you select a product that is to be displayed in a customer’s cart with a discount. The ABSTRACT PRODUCT SKU defines the discounted product, and QUANTITY defines how many products a customer can buy with a discount.

To give away a promotional product for free, select percentage calculator type and enter 100 percents.

Reference information: Define on what conditions the discount can be applied

Similarly to defining discounted products, the conditions on which a discount is applied are defined using a query string. However, the two settings serve different purposes:

SETTING	TAB	PURPOSE
APPLY TO	Discount calculation	Selects the cart items that receive the discount.
APPLY WHEN	Conditions	Determines whether the discount applies to the cart at all.

APPLY WHEN acts as a gate: if its decision rules are not fulfilled, the discount is not applied. APPLY TO then selects which of the items in the cart the discount value is distributed across. Because of this, APPLY WHEN also offers cart-level and customer-level fields, such as grand-total, total-quantity, and customer-group, while APPLY TO offers only item-level fields, such as sku, item-price, and attribute.<attribute_key>.

The fields that appear in both places have a different meaning in each. For example, sku under APPLY WHEN checks whether the cart contains an item with a given SKU, while sku under APPLY TO restricts the discount to the items with that SKU.

Example: The discount is applied if five or more items are in the cart, and if it’s Tuesday or Wednesday.

The THE DISCOUNT CAN BE APPLIED IF THE QUERY APPLIES FOR AT LEAST X ITEM(S). defines a minimum number of items that must fulfill the query for the discount to be applies. By default, the minimum order amount value is 1. It means that the discount is applied if there is one item in a cart the fulfills the query.

Example: The discount is applied if 4 or more items with an Intel Core processor are in the cart.

Reference information: Generate voucher codes

ATTRIBUTE	DESCRIPTION
QUANTITY	The number of vouchers to generate.
CUSTOM CODE	Any custom symbols you want the voucher codes to contain. If you are adding a single custom code, for ADD RANDOM GENERATED CODE LENGTH, select No additional random characters. If you add random characters, they are by default appended to the end of the custom code. To specify where to place the random characters, add `[code]` to the custom code. For example, `black[code]friday`.
ADD RANDOM GENERATED CODE LENGTH	A number of random alphanumeric symbols to add to the code. If you entered a CUSTOM CODE, the random characters are appended to the end of it. If you are generating more than one code, you must select 3 or more.
MAX NUMBER OF USES	Defines the maximum number of times a voucher code can be redeemed.

Voucher code collections

The voucher codes of a discount belong to a voucher code collection. One customer may only redeem one voucher code per collection per cart. At the same time, a customer can redeem two vouchers in one cart if they belong to different voucher code collections.

Decision rules: Attributes and operators

This section describes complex decision rule attributes:

ATTRIBUTE	VALUE TYPE	DESCRIPTION
calendar-week	Number	The number of a week in a year: 1-52.
grand-total	Decimal number	The sum of all totals.
sub-total	Decimal number	The sum of item prices without shipment expenses and discounts.
item-price	Decimal number	The price of one item.
item-quantity	Number	The number of items.
month	Number	The month of the year: 1-12.
time	hour:minute	The time of the day.
total-quantity	Number	The total cart quantity.
attribute.*	String, number, list	One field per product attribute key in your database, named `attribute.<attribute_key>`. If no attribute keys exist, no attribute fields are available.
customer-group	String	Any value, use a customer group name for an exact match.
customer-order-count	Number	Any value. Checked against the number of placed orders in a customer account.
product-offer-reference	String	Unique identifier of a product offer. Marketplace only.

RELATION OPERATOR	IN PLAIN QUERY	VALUE TYPE	DESCRIPTION
Contains	CONTAINS	String, Number	Checks if the value is contained in the field.
Doesn’t contain	DOES NOT CONTAIN	String, Number	Checks if the value is not contained in the field.
Equal	=	String, Number	Checks if the value is equal to the value of the right operand
Not Equal	!=	String, Number	Checks if the value is not equal to the value of the right operand
In	IS IN	List	Values need to be semicolon-separated
Not In	IS NOT IN	List	Values need to be semicolon-separated
Less	<	Number	Checks if the value is less than the value of the right operand
Less or equal	<=	Number	Checks if the value is less than or equal to the value of the right operand
Greater	>	Number	Checks if the value is greater than the value of the right operand
Greater or equal	>=	Number	Checks if the value is greater than or equal to the value of the right operand

The operators offered for a field depend on the value types that the field accepts, so not every field offers all of the operators above. For example:

FIELD	OPERATORS OFFERED
`attribute.<attribute_key>`	Equal, Not equal, Contains, Doesn’t contain, In, Not in, Less, Less or equal, Greater, Greater or equal
`sku`	Equal, Not equal, Contains, Doesn’t contain, In, Not in
`item-price`	Equal, Not equal, Contains, Doesn’t contain, Less, Less or equal, Greater, Greater or equal

Missing operators

If a field offers fewer operators than you expect, the field accepts fewer value types. Attribute fields accept strings, numbers, and lists, so they offer all of the operators. A field that accepts only lists offers In and Not in only. Operators that are costly to evaluate for a value type are left out for performance reasons.

Promotions & Discounts feature overview

Tue, 15 Sep 2026 09:26:21 +0000

The *Discount Management* feature lets shop owners provide free value to their customers by discounting the percentage or fixed sum of an order's subtotal, or an item's price on predefined conditions. ## Discount types There are two discount types: - Voucher - Cart rule A Back Office user selects a discount type when [creating a discount](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html). ## Voucher A *voucher* is a discount that applies when a customer enters an active voucher code on the **Cart** page. ![Cart voucher](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/cart_voucher.png) Once the customer clicks **Redeem code**, the page refreshes to show the discount name, discount value, and available actions: **Remove** and **Clear all**. The **Clear all** action disables all the applied discounts. The **Remove** action disables a single discount. ![Cart voucher applied](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/cart_voucher_applied.png) You can generate multiple voucher codes for a single voucher. The code has a **Max number of uses** value which defines how many times the code can be redeemed. You can enter codes manually or use the code generator in the Back Office. ![Generate codes](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+%26+Discounts/Discount/Discount+Feature+Overview/generate_codes.png) To learn how a Back Office user can create a voucher in the Back Office, see [Create discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) ## Cart rule A *cart rule* is a discount that applies to a cart once all the [decision rules](#decision-rule) linked to the cart rule are fulfilled. A cart rule is applied automatically once its conditions are met. If the decision rules of a discount are fulfilled, the customer can see the discount upon entering the cart. Unlike with [vouchers](#voucher), the **Clear all** and **Remove** actions are not displayed for cart rules. ![Cart rule](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/cart-cart-rule.png) To learn how a Back Office user can create a cart rule in the Back Office, see [Create discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) ### Decision rule In the Back Office, you define discounts by building a query. A query consists of one or more rules, and each rule compares a parameter to a value using a relation operator. Such a rule is called a *decision rule*. A query serves one of two purposes, depending on where you build it: - Under **Apply when**, the query is a condition: it determines whether the discount applies to the cart at all. - Under **Apply to**, the query is a filter: it selects which items in the cart receive the discount. The Back Office does not use the term *decision rule*. You build queries in the **Apply when** and **Apply to** fields, which are described in [Apply to compared to Apply when](#apply-to-compared-to-apply-when). A query can contain one or more rules. Find an example combination below: | PARAMETER | RELATION OPERATOR | VALUE | | --- | --- | --- | | total-quantity | equal | 3 | | day-of-week | equal | 5 | In this case, the discount is applied if the cart contains three items and the purchase is made on the fifth day of the week (Friday). Multiple rules form a single query. A query is a request for information based on the defined parameters. In the Discount Management capability, a query requests information from a cart, either to check whether the cart is eligible for the discount or to select the items to discount. By specifying rules, you define the parameters of the query. In the Back Office, you create the rules in a Query Builder. Query Builder transforms the rules into a single query. The rules from the previous example look as follows in the Query Builder: ![Query Builder showing the rules total-quantity equal 3 and day-of-week equal 5 combined with AND](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/discount-management/latest/marketplace/marketplace-promotions-discounts-feature-overview/image-1788795776069.png) A Back Office user can enter a query manually as well. The same rules look as follows as a plain query: `total-quantity = '3' AND day-of-week = '5'` You can switch between Query Builder and Plain query modes to see how the specified rules look in either of them. Decision rules are combined with *AND* and *OR* combination operators. With the AND operator, all the rules must be fulfilled for the discount to be applied. With the OR operator, at least one must be fulfilled for the discount to be applied. In the following example, for the discount to apply the cart must contain three items, and the purchase must be made on Wednesday. ![AND operator](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+%26+Discounts/Discount/Discount+Feature+Overview/and-operator.png) In the following example, for the discount to apply, either the cart must contain three items, or the purchase must be made on Wednesday. ![OR operator](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+%26+Discounts/Discount/Discount+Feature+Overview/or-operator.png) {% info_block infoBox "Info" %} When rules are combined by the OR operator, they do not exclude each other. If a cart fulfills both such rules, the discount is still applied. {% endinfo_block %} #### Product attributes in decision rules To use a product attribute in a decision rule, reference it as `attribute.` — for example, `attribute.color`. Spryker does not predefine these fields: it generates one field per product attribute key that exists in your database. {% info_block warningBox "Add attribute keys before you use them" %} If you do not see the attribute you expect in the Query Builder, the corresponding attribute key does not exist in your database. Add it in one of the following ways: - [Create product attributes](/docs/pbc/all/product-information-management/latest/base-shop/manage-in-the-back-office/attributes/create-product-attributes.html) in the Back Office. - Import attribute keys with the `product-attribute-key` data entity. For details, see [Import file details: product_attribute_key.csv](/docs/pbc/all/product-information-management/latest/base-shop/import-and-export-data/products-data-import/import-file-details-product-attribute-key.csv.html). {% endinfo_block %} The examples in this document use attribute keys such as `attribute.color` and `attribute.processor_cores`. Depending on the demo shop you started with, these keys may not exist in your database. Replace them with the attribute keys that exist in your own database. #### Decision rule group A *rule group* is a separate set of rules with its own combination operator. ![Decision rule group](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+%26+Discounts/Discount/Discount+Feature+Overview/decision-rule-group.png) With the rule groups, you can build multiple levels of rule hierarchy. When a cart is evaluated against the rules, it's evaluated on all levels of the hierarchy. At each level, there can be both rules and rule groups. ![Decision rule hierarchy](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+%26+Discounts/Discount/Discount+Feature+Overview/decision-rule-hierarchy.png) When a cart is evaluated on a level that has both a rule and a rule group, the rule group is treated as a single rule. The following diagram shows how a cart is evaluated against the rules from the previous screenshot. ### Discount threshold A *threshold* is the minimum number of items in a cart that must fulfill all the specified decision rules for the discount to apply. The default value is *1*. This means that a discount is applied if at least one item fulfills the discount's decision rules. In the following example, the discount is applied if there are four items with an Intel Core processor in the cart. ![Threshold](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/threshold.png) ## Discount application *Discount application* is a discount configuration option that defines the products to which a discount is applied. There are two types of the discount application: - Query string - Promotional product ### Apply to compared to Apply when A discount is configured in two separate places that serve different purposes: | CONFIGURATION | BACK OFFICE TAB | SECTION HEADING | PURPOSE | | --- | --- | --- | --- | | **APPLY TO** | Discount calculation | Define what to apply the discount to | Selects the cart items that receive the discount. | | **APPLY WHEN** | Conditions | Define when to apply the discount | Determines whether the discount applies to the cart at all. | *Apply when* acts as a gate: if its decision rules are not fulfilled, the discount is not applied to the cart. *Apply to* then selects which of the items in the cart the discount value is distributed across. Because the two settings serve different purposes, they offer different fields. *Apply when* evaluates the cart as a whole, so it also offers cart-level and customer-level fields, such as `grand-total`, `sub-total`, `total-quantity`, `currency`, `day-of-week`, and `customer-group`. *Apply to* selects individual items, so it offers only item-level fields, such as `sku`, `item-quantity`, `item-price`, `category`, and `attribute.`. Some fields, such as `sku`, `item-quantity`, and `item-price`, are available in both places, where they have a different meaning: | FIELD | UNDER APPLY WHEN | UNDER APPLY TO | | --- | --- | --- | | `sku` | Checks whether the cart contains an item with this SKU. | Restricts the discount to the items with this SKU. | | `item-quantity` | Checks whether an item with this quantity is in the cart. | Restricts the discount to the items with this quantity. | | `item-price` | Checks whether an item with this price is in the cart. | Restricts the discount to the items with this price. | The fields under *Apply to* do not discount an SKU or a quantity by themselves. They narrow down the set of items that the discount is applied to. The following screenshots show the same rule in both places. The field list offered under *Apply to* is a subset of the one offered under *Apply when*, because *Apply to* only offers item-level fields. The attribute key in these screenshots comes from the demo data, so the key you see in your own project differs. On the **Discount calculation** tab, *Apply to* selects the items that receive the discount: ![Apply to on the Discount calculation tab, with the rule attribute.farbe equal](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/discount-management/latest/marketplace/marketplace-promotions-discounts-feature-overview/image-1788793722162.png) On the **Conditions** tab, *Apply when* determines whether the discount applies to the cart at all: ![Apply when on the Conditions tab, with the rule attribute.farbe equal](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/discount-management/latest/marketplace/marketplace-promotions-discounts-feature-overview/image-1788793729064.png) {% info_block infoBox "Example" %} A discount with *Apply when* set to `total-quantity >= 10` and *Apply to* set to `attribute.color = 'white'` first checks the total number of items in the cart, regardless of their color. If the cart contains at least ten items, the discount then reduces the price of the white items only. {% endinfo_block %} ### Query string A *query string* is a discount application type that uses [decision rules](#decision-rule) to dynamically determine which products qualify for discounts. The discount in the example below applies to white color products. ![Query collection](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/collection-query.png) The product selection based on the query string is dynamic: - If at some point the color attribute of a product changes from white to anything else, the product is no longer eligible for a discount. - If at some point a product receives the white color attribute, it becomes eligible for a discount. {% info_block infoBox "Attribute keys in the examples" %} This example uses the `attribute.color` field. Attribute fields are generated from the product attribute keys in your own database, so replace `attribute.color` with an attribute key that exists in your database. For details, see [Product attributes in decision rules](#product-attributes-in-decision-rules). {% endinfo_block %} ### Promotional product *Promotional product* is a discount application type that discounts particular products at a set quantity, enabling "buy X, get Y" promotions. When a customer meets conditions for a promotional product discount, the **Promotional products** section is displayed in the cart and lets customers add the available quantity of the discounted products. The section consists of the product name, SKU, original and discounted price, and a description of the discount. ![Promotional product](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/user/features/promotions-discounts-feature-overview.md/202200.0/promotional-product-storefront.png) A Back Office user selects promotional products by entering comma-separated abstract product SKUs in the Back Office. They also define the maximum quantity of the products to be sold with a discount. For example, there are 10 SKUs in **ABSTRACT PRODUCT SKU(S)**, and **MAXIMUM QUANTITY** is set to `1`. If a customer fulfills the discount conditions, they are eligible for one unit of any of the 10 promotional products, not one of each. Likewise, if **MAXIMUM QUANTITY** is set to `3`, they can select 3 units of any of the promotional products in any combination. The promotional products are automatically merchandised below the items in a customer's cart. The customer can add one of these products to the cart from this widget, and the discount will apply. {% info_block infoBox "Note" %} The promotional product discount only applies if the product is added to the cart from the **Promotional Products cart** widget. If the product is already in the cart before the discount conditions are met, the customer needs to first remove it, then re-add it to the widget. {% endinfo_block %} A Back Office user can either give away promotional products for free or provide a discount for these products by specifying the percentage value, or a fixed amount, to be discounted from their price. When giving a product for free, the percentage value must be 100%. Using a fixed amount discount for a free product is also possible, where the amount is equal to a product's price, but it's not recommended because of the possibility of price fluctuations and differences across multiple products. ![Collection - promotional product](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/user/features/promotions-discounts-feature-overview.md/202200.0/collection-promotional-product.png) ## Discount calculation types Calculation defines the value to be deducted from a product's default price. There are two types of discount calculations: - Percentage - Fixed amount {% info_block infoBox %} With the fixed amount type, the currency of the respective shop is used for calculation. {% endinfo_block %} See examples in the table below. | PRODUCT PRICE | CALCULATION TYPE | AMOUNT | DISCOUNT APPLIED | PRICE TO PAY | | --- | --- | --- | --- | --- | | €50 | Percentage | 10 | €5 | €45 | | €50 | Fixed amount | 10 | €10 | €40 | A Back Office user defines calculation when [creating discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) ![Discount calculation](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/discount_calculation.png) ## Discount exclusiveness *Discount exclusiveness* defines if the discount value of a discount can be combined with the discount value of other discounts in a single order. A Back Office user defines a calculation when [creating discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) ![Exclusive discount](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/user/features/promotions-discounts-feature-overview.md/exclusivity.png) ### Exclusive discount An *exclusive discount* is a discount that when applied to a cart, discards all the other discounts applied to it. {% info_block infoBox "Promotional products and query string" %} [Promotional product](#promotional-product) discounts and [query string](#query-string) discounts are separate when it comes to exclusivity. These types of discounts exclude all other discounts only among each other. Promotional product discounts are not affected by exclusive query string discounts and vice versa. {% endinfo_block %} If a cart is eligible for multiple exclusive discounts, you can [prioritize](#discount-priority) the discounts to define which of the exclusive discounts prevail over the others. For details on how a Back Office user can set priorities for discounts, see [Create discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) If the exclusive discounts are not prioritized or have the same priorities, the highest-value discount is applied. For details and examples on how the discounts are calculated, see [Discount calculation logic](#discount-calculation-logic). ### Non-exclusive discount A *non-exclusive discount* is a discount that can be combined with other non-exclusive discounts in a single order. If all the discounts are non-exclusive, they are applied together. However, a Back Office user can [prioritize](#discount-priority) the non-exclusive discounts to set the order in which they apply. For details on how a Back Office user can prioritize a discount, see [Create discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) For details and examples of how discounts are calculated based on their priorities, see [Discount calculation logic](#discount-calculation-logic). ## Discount validity interval A *validity interval* is a period of time during which a discount is active and can be applied. If a cart is eligible for a discount outside of its validity interval, the cart rule is not applied. If a customer enters a voucher code outside of its validity interval, they get a "Your voucher code is invalid." message. A Back Office user defines calculation when [creating a discount](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) ![Validity interval](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/user/features/promotions-discounts-feature-overview.md/validity-interval.png) ## Discount priority In cases when several discounts can apply to a customer's order, a Back Office user can set the discount priorities. A *discount priority* is an integer value that defines the order in which the discounts are applied. For details on how discounts are calculated based on their priorities, see [Discount calculation logic](#discount-calculation-logic). Discount prioritization behavior does not depend on the [discount type](#discount-types). For example, you might have the following priorities for different types: - Cart rule discount with priority 1 - Voucher code discount with priority 2 - Voucher code discount with priority 3 - Cart rule discount with priority 4 In this case, discounts are applied based on their priority, regardless of type. {% info_block infoBox "Info" %} If you have a voucher code and a cart rule with the same priority, both discounts apply and use the same cart subtotal. For an example, see [Scenario 5: Non-exclusive, fixed amount and percentage discounts with the same priority values](#scenario-4-non-exclusive-fixed-amount-and-percentage-discounts-with-the-same-priority-values). {% endinfo_block %} ## Discount calculation logic The discount calculation logic follows these rules: - All discounts are calculated sequentially based on their [priority value](#discount-priority). Thus, discounts with the highest priority value are considered first. - Discounts without priority values are treated with the last possible priority. - Discounts with the same priority value are calculated independently of each other. - If there is a set of discounts with [exclusive](#exclusive-discount) and [non-exclusive](#non-exclusive-discount) discounts, the non-exclusive discounts are ignored. The remaining exclusive discounts are handled according to their priority values as shown in the schema: ![discounts-calculation-logic](https://confluence-connect.gliffy.net/embed/image/ad6c6c4c-9ccb-42ae-a9dc-5944300bdf91.png?utm_medium=live&utm_source=custom) ### Example discount calculation scenarios The following scenarios illustrate how the discount calculation logic works. #### Scenario 1: Multiple non-exclusive discounts, the mix of fixed amount and percentage discount calculation types Cart subtotal: €500 | DISCOUNT NAME| DESCRIPTION| DISCOUNT TYPE| DISCOUNT AMOUNT| DISCOUNT PRIORITY| EXCLUSIVENESS| | --- | --- | --- | --- | --- |--- | | HOCKEY10| 10% off your order| Percentage| 10%| 300| No| | HELMET20| Save €20 on helmets| Fixed amount| €20| 200| No| | STICK50| €50 off all carbon sticks| Fixed amount| €50| 500| No| **Discounts applied in priority order:** 1. HELMET20 (200 priority): €500 - €20 = €480 2. HOCKEY10 (300 priority): €480 - €480*0.10 = €432 3. STICK50 (500 priority): €432 - €50 = €382 **Calculation as displayed in cart:** Subtotal: €500.00 HELMET20: -€20.00 HOCKEY10: -€48.00 STICK50: -€50.00 Grand total: €382.00 {% info_block infoBox "Info" %} As customers are not aware of the logic behind discount prioritization, they may be confused about the assigned priorities. For the scenario above, they might wonder why they get 10% off the pre-discount price of the hockey stick and not the helmet. In cases like this one, instead of creating prioritization logic for separate discount types, consider adjusting the discount priority accordingly to avoid customer confusion. {% endinfo_block %} #### Scenario 2: Multiple non-exclusive discounts, percentage discount calculation types Cart subtotal: $100 | DISCOUNT NAME| DESCRIPTION| DISCOUNT TYPE| DISCOUNT AMOUNT| DISCOUNT PRIORITY| EXCLUSIVENESS| NOTES| | --- | --- | --- | --- | --- |--- |--- | | BUY4GET1| Buy 4 baguettes, get one free| Percentage| 100%| 100| No| One baguette costs $3| | SPICE10| 10% off spices| Percentage| 10%| 100| No| Spices cost $30| | MEMBER5| 5% off for members| Percentage| 5%| 5000| No| | | STORE5| 5% off storewide if you spend $50 or more| Percentage| 5%| 5000|No| | **Discounts applied in priority order:** 1. BUY4GET1 (100 priority): $100 - $3*1.00 or $3 = $97 2. SPICE10 (100 priority): $97 - $30*0.10 or $3.00 = $94 3. MEMBER5 (5000 priority): $94 - $94*0.05 or $4.70 = $89.30 4. STORE5 (5000 priority): $89.30 - $94*0.05 or $4.70 = $84.60 **Calculation as displayed in cart:** Subtotal: $100.00 BUY5GET10: -$3.00 SPICE10: -$3.00 MEMBER5: -$4.70 STORE5: -$4.70 Grand total: $84.60 #### Scenario 3: Multiple discounts, both exclusive and non-exclusive Cart subtotal: $100 | DISCOUNT NAME| DESCRIPTION| DISCOUNT TYPE| DISCOUNT AMOUNT| DISCOUNT PRIORITY| EXCLUSIVENESS| NOTES| | --- | --- | --- | --- | --- |--- |--- | | BUY4GET1| Buy 4 baguettes, get one free| Percentage| 100%| 100| No| One baguette costs $3| | SPICE10| 10% off spices| Percentage| 10%| 100| No| $30 of spices| | MEMBER5| 5% off for members| Percentage| 5%| 5000| Yes| | | STORE5| 5% off storewide if you spend $50 or more| Percentage| 5%| 9000| Yes| | **Discounts applied in priority order:** MEMBER5 (5000): $100 - $100*0.05 = $95 In the presence of exclusive discounts, all non-exclusive discounts are excluded. Between the exclusive discounts, the discount with the higher priority is chosen. #### Scenario 4: Non-exclusive, fixed amount and percentage discounts with the same priority values Cart subtotal: €100 | DISCOUNT NAME| DESCRIPTION| DISCOUNT TYPE| DISCOUNT AMOUNT| DISCOUNT PRIORITY| EXCLUSIVENESS| NOTES | | --- | --- | --- | --- | --- |--- | --- | | 10SOCKS| 10% off Nike socks| Percentage| 10%| 100| No| Nike socks cost €40| | 20PANTS| Save €20 on all white pants| Fixed amount| €20|100| No| White pants cost €60| **Discounts applied in priority order:** 1. 10SOCKS (100 priority): €100 - €40*0.1 = €96 2. 20PANTS (100 priority): €96 - €20 = €76 **Calculation as displayed in cart:** Subtotal: €100.00 10SOCKS: -€4 20PANTS: -€20.00 Grand total: €76.00 #### Scenario 5: Exclusive and non-exclusive discounts without the priorities Cart subtotal: €100 | DISCOUNT NAME | DESCRIPTION| DISCOUNT TYPE | DISCOUNT AMOUNT | DISCOUNT PRIORITY| EXCLUSIVENESS | NOTES | | --- | --- | --- | --- | --- |--- |--- | |10SOCKS | 10% off Nike socks | Percentage | 10% | |Exclusive | Nike socks cost €40 | |5PANTS|Save €5 on all pants| Fixed amount | €5 | | Exclusive | | |SITE10|10% off everything in the store| Percentage | €10 | | Non-exclusive | | In the presence of exclusive discounts, all non-exclusive discounts are excluded. Since the remaining exclusive discounts do not have priorities and the discount 5PANTS provides more free value than the discount 10SOCKS, this discount is applied. **Calculation as displayed in cart:** Subtotal: €100.00 15PANTS: -€5 Grand total: €95.00 ## Related Business User articles |BACK OFFICE USER GUIDES| |---| | [Create a discount](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html) | | [Edit discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/edit-discounts.html) | ## Related Developer articles | INSTALLATION GUIDES | UPGRADE GUIDES | GLUE API GUIDES | DATA IMPORT | TUTORIALS AND HOWTOS | |---|---|---|---|---| | [Integrate the Promotions & Discounts feature](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/install-features/install-the-promotions-and-discounts-feature.html) | [Upgrade the Discount module](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/upgrade-modules/upgrade-the-discount-module.html) | [Add items with discounts to carts of registered users](/docs/pbc/all/discount-management/latest/base-shop/manage-using-glue-api/glue-api-add-items-with-discounts-to-carts-of-registered-users.html) | [File details: discount.csv](/docs/pbc/all/discount-management/latest/base-shop/import-and-export-data/import-file-details-discount.csv.html) | [HowTo: Create discounts based on shipment](/docs/pbc/all/discount-management/latest/base-shop/create-discounts-based-on-shipment.html) | | [Integrate the Category Management + Promotions & Discounts feature](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/install-features/install-the-promotions-and-discounts-category-management-feature.html) | [Upgrade the DiscountCalculatorConnector module](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/upgrade-modules/upgrade-the-discountcalculatorconnector-module.html) | [Retrieve discounts in carts of registered users](/docs/pbc/all/discount-management/latest/base-shop/manage-using-glue-api/glue-api-retrieve-discounts-in-carts-of-registered-users.html) | ["Import file details: discount_amount.csv"](/docs/pbc/all/discount-management/latest/base-shop/import-and-export-data/import-file-details-discount-amount.csv.html) | | | [Integrate the Product labels + Promotions & Discounts feature](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/install-features/install-the-promotions-and-discounts-product-labels-feature.html) | [Upgrade the DiscountPromotion module](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/upgrade-modules/upgrade-the-discountpromotion-module.html) | [Manage discount vouchers in carts of registered users](/docs/pbc/all/discount-management/latest/base-shop/manage-using-glue-api/glue-api-manage-discount-vouchers-in-carts-of-registered-users.html) | ["Import file details: discount_store.csv"](/docs/pbc/all/discount-management/latest/base-shop/import-and-export-data/import-file-details-discount-store.csv.html) | | | [Integrate the Promotions & Discounts Glue API](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/install-features/install-the-promotions-and-discounts-glue-api.html) | [Upgrade the DiscountPromotionWidget module](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/upgrade-modules/upgrade-the-discountpromotionwidget-module.html) | [Add items with discounts to guest carts](/docs/pbc/all/discount-management/latest/base-shop/manage-using-glue-api/glue-api-add-items-with-discounts-to-guest-carts.html) | ["Import file details: discount_voucher.csv"](/docs/pbc/all/discount-management/latest/base-shop/import-and-export-data/import-file-details-discount-voucher.csv.html) | | | | [Upgrade the DiscountSalesAggregatorConnector module](/docs/pbc/all/discount-management/latest/base-shop/install-and-upgrade/upgrade-modules/upgrade-the-discountsalesaggregatorconnector-module.html) | [Retrieve discounts in guest carts](/docs/pbc/all/discount-management/latest/base-shop/manage-using-glue-api/glue-api-retrieve-discounts-in-guest-carts.html) | | | | | | [Manage discount vouchers in guest carts](/docs/pbc/all/discount-management/latest/base-shop/manage-using-glue-api/glue-api-manage-discount-vouchers-in-guest-carts.html) | | | | | | [Retrieve discounts in customer carts](/docs/pbc/all/discount-management/latest/base-shop/manage-using-glue-api/glue-api-retrieve-discounts-in-customer-carts.html) | | |

Marketplace Promotions & Discounts feature overview

Tue, 15 Sep 2026 09:26:21 +0000

The *Marketplace Promotions and Discounts* feature ensures that discounts are applied to orders. There are two discount types: - Voucher - Cart rule A product catalog manager selects a discount type when [creating a discount](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html). Based on the business logic, discounts can be applied in the following ways: - The discount is applied to the whole Marketplace order. In such a scenario, the discount is distributed among all the merchant orders and calculated according to the total volume of each of the items. ![Merchant discount 1](https://spryker.s3.eu-central-1.amazonaws.com/docs/Marketplace/user+guides/Features/Marketplace+Order+Management/mp-discount-1.png) - The discount is related to a single product item in the Marketplace order. In this case, the whole discount is assigned only to the merchant order that contains the discounted item. ![Merchant discount 2](https://spryker.s3.eu-central-1.amazonaws.com/docs/Marketplace/user+guides/Features/Marketplace+Order+Management/mp-discount-2.png) ## Voucher A *Voucher* is a discount that applies when a customer enters an active voucher code on the *Cart* page. ![Cart voucher](https://spryker.s3.eu-central-1.amazonaws.com/docs/Marketplace/user+guides/Features/Marketplace+Promotions+and+Discounts+feature+overview/voucher-storefront.png) Once the customer clicks **Redeem code**, the page refreshes to show the discount name, discount value, and available actions: **Remove** and **Clear all**. The **Clear all** action disables all the applied discounts. The **Remove** action disables a single discount. ![Cart voucher applied](https://spryker.s3.eu-central-1.amazonaws.com/docs/Marketplace/user+guides/Features/Marketplace+Promotions+and+Discounts+feature+overview/voucher-cart.png) Multiple voucher codes can be generated for a single voucher. The code has a **Max number of uses** value which defines how many times the code can be redeemed. You can enter codes manually or use the code generator in the Back Office. ![Generate codes](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/generate_codes.png) To learn how a product catalog manager can create a voucher in the Back Office, see [Creating a voucher](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html). ## Cart Rule A *cart rule* is a discount that applies to the cart once all the [decision rules](#decision-rule) linked to the cart rule are fulfilled. The cart rule is applied automatically. If the decision rules of a discount are fulfilled, the customer can see the discount upon entering the cart. Unlike with [vouchers](#voucher), the **Clear all** and **Remove** actions are not displayed. ![Cart rule](https://spryker.s3.eu-central-1.amazonaws.com/docs/Marketplace/user+guides/Features/Marketplace+Promotions+and+Discounts+feature+overview/cart-rule-storefront.png) To learn how a product catalog manager can create a cart rule in the Back Office, see [Create discounts](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html). ### Decision rule In the Back Office, you define discounts by building a query. A query consists of one or more rules, and each rule compares a parameter to a value using a relation operator. Such a rule is called a *decision rule*. A query serves one of two purposes, depending on where you build it: - Under **Apply when**, the query is a condition: it determines whether the discount applies to the cart at all. - Under **Apply to**, the query is a filter: it selects which items in the cart receive the discount. The Back Office does not use the term *decision rule*. You build queries in the **Apply when** and **Apply to** fields, which are described in [Apply to compared to Apply when](#apply-to-compared-to-apply-when). A query can contain one or more rules. Find an exemplary combination below: | PARAMETER | RELATION OPERATOR | VALUE | | --- | --- | --- | | total-quantity | equal | 3 | | day-of-week| equal | 5 | In this case, the discount is applied if the cart contains three items and the purchase is made on the fifth day of the week (Friday). Multiple rules form a single query. A query is a request for information based on the defined parameters. In the Discount feature, a query requests information from a cart, either to check whether the cart is eligible for the discount or to select the items to discount. By specifying rules, you define the parameters of the query. In the Back Office, a product catalog manager creates the rules in a Query Builder. The rules created in the Query Builder are transformed into a single query. The rules from the previous example look as follows in the Query Builder:

![Query Builder showing the rules total-quantity equal 3 and day-of-week equal 5 combined with AND](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/discount-management/latest/marketplace/marketplace-promotions-discounts-feature-overview/image-1788795776069.png)

A product catalog manager can enter the query manually as well. The same rules look as follows as a plain query:

![Plain query](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/plain-query.png)

You can switch between Query Builder and Plain query modes to see how the specified rules look in either of them. Decision rules are combined with *AND* and *OR* combination operators. With the AND operator, all the rules should be fulfilled for the discount to be applied. With the OR operator, at least one of them should be fulfilled for the discount to be applied. In the following example, for the discount to be applied, a cart should contain three items, and the purchase should be made on Wednesday. ![AND operator](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/and-operator.png) In the following example, for the discount to be applied, a cart should contain three items, or the purchase should be made on Wednesday. ![OR operator](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/or-operator.png) {% info_block infoBox "Info" %} When rules are combined by the OR operator, they do not exclude each other. If a cart fulfills both such rules, the discount is still applied. {% endinfo_block %} #### Product attributes in decision rules To use a product attribute in a decision rule, reference it as `attribute.` — for example, `attribute.color`. Spryker does not predefine these fields: it generates one field per product attribute key that exists in your database. {% info_block warningBox "Add attribute keys before you use them" %} If you do not see the attribute you expect in the Query Builder, the corresponding attribute key does not exist in your database yet. Add it in one of the following ways: - [Create product attributes](/docs/pbc/all/product-information-management/latest/base-shop/manage-in-the-back-office/attributes/create-product-attributes.html) in the Back Office. - Import attribute keys with the `product-attribute-key` data entity. For details, see [Import file details: product_attribute_key.csv](/docs/pbc/all/product-information-management/latest/base-shop/import-and-export-data/products-data-import/import-file-details-product-attribute-key.csv.html). {% endinfo_block %} The examples in this document use attribute keys such as `attribute.color` and `attribute.processor_cores`. Depending on the demo shop you started with, these keys may not exist in your database. Replace them with the attribute keys that exist in your own database. #### Decision rule group A rule group is a separate set of rules with its own combination operator. ![Decision rule group](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+%26+Discounts/Discount/Discount+Feature+Overview/decision-rule-group.png) With the rule groups, you can build multiple levels of rule hierarchy. When a cart is evaluated against the rules, it is evaluated on all levels of the hierarchy. On each level, there can be both rules and rule groups. ![Decision rule hierarchy](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+%26+Discounts/Discount/Discount+Feature+Overview/decision-rule-hierarchy.png) When a cart is evaluated on a level that has a rule and a rule group, the rule group is treated as a single rule. The following diagram shows how a cart is evaluated against the rules in the previous screenshot. ### Discount threshold A *threshold* is a minimum number of items in the cart that should fulfill all the specified decision rules for the discount to be applied. The default value is *1*. It means that a discount is applied if at least one item fulfills the discount's decision rules. In the following example, the discount is applied if there are four items with the Intel Core processor in the cart. ![Threshold](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/threshold.png) ## Discount application Discount application is a discount configuration option that defines the products to which a discount is applied. The Marketplace discounts are applied based on the query string. The *query string* is a discount application type that uses [decision rules](#decision-rule) to dynamically define what products a discount applies to. The discount in the following example applies to white products. ![Query collection](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/collection-query.png) The product selection based on the query string is dynamic: - If at some point, the color attribute of a product changes from white to anything else, the product is no longer eligible to be discounted. - If at some point, a product receives the white color attribute, it becomes eligible for the discount. {% info_block infoBox "Attribute keys in the examples" %} This example uses the `attribute.color` field. Attribute fields are generated from the product attribute keys in your own database, so replace `attribute.color` with an attribute key that exists in your database. For details, see [Product attributes in decision rules](#product-attributes-in-decision-rules). {% endinfo_block %} ### Apply to compared to Apply when A discount is configured in two separate places that serve different purposes: | CONFIGURATION | BACK OFFICE TAB | SECTION HEADING | PURPOSE | | --- | --- | --- | --- | | **APPLY TO** | Discount calculation | Define what to apply the discount to | Selects the cart items that receive the discount. | | **APPLY WHEN** | Conditions | Define when to apply the discount | Determines whether the discount applies to the cart at all. | *Apply when* acts as a gate: if its decision rules are not fulfilled, the discount is not applied to the cart. *Apply to* then selects which of the items in the cart the discount value is distributed across. Because the two settings serve different purposes, they offer different fields. *Apply when* evaluates the cart as a whole, so it also offers cart-level and customer-level fields, such as `grand-total`, `sub-total`, `total-quantity`, `currency`, `day-of-week`, and `customer-group`. *Apply to* selects individual items, so it offers only item-level fields, such as `sku`, `item-quantity`, `item-price`, `category`, and `attribute.`. Some fields, such as `sku`, `item-quantity`, and `item-price`, are available in both places, where they have a different meaning: | FIELD | UNDER APPLY WHEN | UNDER APPLY TO | | --- | --- | --- | | `sku` | Checks whether the cart contains an item with this SKU. | Restricts the discount to the items with this SKU. | | `item-quantity` | Checks whether an item with this quantity is in the cart. | Restricts the discount to the items with this quantity. | | `item-price` | Checks whether an item with this price is in the cart. | Restricts the discount to the items with this price. | The fields under *Apply to* do not discount an SKU or a quantity by themselves. They narrow down the set of items that the discount is applied to. The following screenshots show the same rule in both places. The field list offered under *Apply to* is a subset of the one offered under *Apply when*, because *Apply to* only offers item-level fields. The attribute key in these screenshots comes from the demo data, so the key you see in your own project differs. On the **Discount calculation** tab, *Apply to* selects the items that receive the discount: ![Apply to on the Discount calculation tab, with the rule attribute.farbe equal](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/discount-management/latest/marketplace/marketplace-promotions-discounts-feature-overview/image-1788793722162.png) On the **Conditions** tab, *Apply when* determines whether the discount applies to the cart at all: ![Apply when on the Conditions tab, with the rule attribute.farbe equal](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/discount-management/latest/marketplace/marketplace-promotions-discounts-feature-overview/image-1788793729064.png) {% info_block infoBox "Example" %} A discount with *Apply when* set to `total-quantity >= 10` and *Apply to* set to `attribute.color = 'white'` first checks the total number of items in the cart, regardless of their color. If the cart contains at least ten items, the discount then reduces the price of the white items only. {% endinfo_block %} ## Discount calculation Calculation defines the value to be deducted from a product's original price. There are two types of discount calculation: - Calculator percentage - Calculator fixed {% info_block infoBox "Info" %} With the calculator fixed type, the currency of the respective shop is used for calculation. {% endinfo_block %} See examples in the following table. | PRODUCT PRICE | CALCULATION TYPE | AMOUNT | DISCOUNT APPLIED | PRICE TO PAY | | --- | --- | --- | --- | --- | | €50 | Calculator percentage | 10 | €5 | €45 | | €50 | Calculator fixed | 10 | €10 | €40 | A product catalog manager defines the calculation when [creating a voucher or a cart rule](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html). ![Discount calculation](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/discount_calculation.png) ## Discount exclusiveness Discount exclusiveness defines if a discount value of a discount can be combined with the discount value of other discounts in a single order. A product catalog manager defines exclusiveness when [creating a voucher or a cart rule](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html). ![Exclusive discount](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/exclusivity.png) ### Exclusive discount An exclusive discount is a discount that, when applied to a cart, discards all the other discounts applied to it. If a cart is eligible for multiple exclusive discounts, the highest-value discount is applied. In the following example, a cart with the order total amount of €100 contains the following discounts. | DISCOUNT NAME | DISCOUNT AMOUNT | DISCOUNT TYPE | EXCLUSIVENESS | DISCOUNTED AMOUNT | | --- | --- | --- | --- | --- | | D1 | 15 | Calculator percentage | Exclusive | €15 | |D2|5| Calculator fixed | Exclusive | €5 | |D3|10| Calculator percentage | Non-exclusive | €10 | The discount exclusivity is resolved as follows: 1. The discounts D1 and D2 are exclusive, so the non-exclusive discount D3 is discarded. 2. The discount D1 provides more free value than the discount D2. 3. As a result, the discount D1 is applied. ### Non-exclusive discount A non-exclusive discount is a discount that can be combined with other non-exclusive discounts in a single order. In the following example, a cart with the order total amount of €30 contains the following discounts. | DISCOUNT NAME | DISCOUNT AMOUNT | DISCOUNT TYPE | EXCLUSIVENESS | DISCOUNTED AMOUNT | | --- | --- | --- | --- | --- | | D1 | 15 | Calculator percentage | Non-exclusive | €15 | | D2 | 5 | Calculator fixed | Non-exclusive | €5 | | D3 | 10 |Calculator percentage | Non-exclusive | €10 | As all the discounts are non-exclusive, they are applied together. ## Discount validity interval A *validity interval* is a time period during which a discount is active and can be applied. If a cart is eligible for a discount outside of its validity interval, the cart rule is not applied. If a customer enters a voucher code outside of its validity interval, they get a "Your voucher code is invalid." message. A product catalog manager defines the validity interval when [creating a discount](/docs/pbc/all/discount-management/latest/base-shop/manage-in-the-back-office/create-discounts.html). ![Validity interval](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Promotions+&+Discounts/Discount/Discount+Feature+Overview/validity-interval.png) ## Related Developer articles | INSTALLATION GUIDES| | -------------- | | [Install the Marketplace Promotions & Discounts feature](/docs/pbc/all/discount-management/latest/marketplace/install-the-marketplace-promotions-discounts-feature.html) | | [Install the Marketplace Merchant + Promotions & Discounts feature](/docs/pbc/all/merchant-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-merchant-promotions-and-discounts-feature.html) | | [Install the Marketplace Product Offer + Promotions & Discounts feature](/docs/pbc/all/offer-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-product-offer-promotions-and-discounts-feature.html) |

Workflows feature overview

Mon, 14 Sep 2026 14:50:54 +0000

{% info_block warningBox "Early Access" %} This feature is in Early Access. We'd love for you to try it out and share feedback as we work toward general availability. {% endinfo_block %} The Workflows feature lets Back Office users design, adjust, and monitor multi-step business processes — such as B2B company onboarding, order escalations, or approval flows — directly in the Back Office, without a code deployment. ![The Workflows list in the Back Office, showing the 3-step setup guide and the CompanyOnboarding workflow with its status, active version, and triggers](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/back-office/base-shop/workflow-feature-overview/workflows-1.png) ## Business problems it solves Multi-step business processes are often hard-coded into a project, which creates friction: - **Every process change needs a developer and a deployment.** Adding a step, changing who approves it, or adjusting a timeout normally means a code change and a release. - **Process logic is invisible to the business.** Without reading source code or asking a developer, business teams cannot see or explain how a process actually behaves. - **Ad hoc tracking does not scale.** Teams fall back to spreadsheets, shared inboxes, or manual reminders to track where a company, order, or customer stands in a process, with no single source of truth. The Workflows feature removes the deployment dependency. Unlike a classic state machine, which lives in a deployed code file and requires a release to change, a workflow is designed, versioned, and activated directly in the Back Office. A visual builder lets you draw the process—adding steps and linking them—on a canvas, so process design is in the hands of the people who own the process, without writing state-machine XML by hand. ## How a workflow works A workflow describes how a subject — which can be anything: a company, a user, a product, or any custom entity — moves through a sequence of steps as events occur, conditions are met, or timeouts elapse. A workflow starts when its subject reaches a specific application event, defined in a trigger: for example a company being created, a user registering, or a merchant being updated. Consider onboarding a new B2B company. When a company is created, a workflow starts and walks it through a series of steps: *business verification*, then *contract agreement*, then *customer group assignment*, and finally *approved*. Some steps advance on their own once a condition is met (for example, the business has been verified); others wait for a Back Office user to confirm; and a step can time out if nothing happens. The whole process — its steps, their order, and the rules between them — is defined and adjusted in the Back Office, not in code. The Back Office renders this as a diagram, so you can follow the flow without reading the underlying definition: ![The CompanyOnboarding workflow graph in the Back Office, showing the created, business verification, contract agreement, and customer group assignment steps, with a branch to denied if the business is not verified](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/back-office/base-shop/workflow-feature-overview/workflows-3.png) The example below simplifies this to its first decision point — verifying the business, then approving or denying — to show the underlying definition format from start to finish: a new company moves from `created` to `approved`, passing a verification check and an automatic waiting step along the way. A workflow definition is an XML document in the `state-machine-01` format. It has three parts: `states`, `transitions`, and `events`: ```xml {% raw %} created business verification initiate business verification approved verify business business verification denied verify business {% endraw %} ``` You do not write this XML by hand. On the **Create Version** screen, a visual builder lets you draw the states and transitions on a canvas and set each one's properties in an inspector. The raw XML above is still available through the builder's advanced panel for review or direct editing. ![The Create Version screen in the Back Office, with the visual builder showing the workflow states on a canvas and the properties inspector on the right](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/back-office/base-shop/workflow-feature-overview/workflows-2.png) Here is how a company travels through this definition: 1. **The instance starts.** A trigger (see [Triggers](#triggers)) starts an instance for a new company. The instance begins in the initial state you set when you author the version — here, `created`. 2. **An `onEnter` event fires automatically.** The `initiate` event is marked `onEnter="true"`, so the engine fires it as soon as the instance is in `created`, moving the company to `business verification`. 3. **A timeout waits, then a condition decides.** The `verify business` event has a `timeout="3 second"`. After the timeout elapses, the engine evaluates the two `verify business` transitions in order. The first is guarded by the `CompanyOnboarding/IsBusinessVerified` condition: if it returns `true`, the company moves to `approved`. If not, the unguarded transition sends it to `denied`. Three ideas in that trace do the heavy lifting, and each maps to a piece of project code a developer can plug in: | In the definition | What it means | You provide | |-------------------|---------------|-------------| | `event` | A named step. It can fire automatically (`onEnter`), after a delay (`timeout`), on a user action (`manual`), or from application code. | Nothing — events are declared in the XML. | | `condition="…"` | A guard that lets a transition fire only when a business rule is true. | A [condition plugin](#conditions). | | `command="…"` | Project logic to run during a transition (not shown above — for example, "mark the company approved"). | A [command plugin](#commands). | ## Core concepts A workflow is built from four entities. The example above is a *version* of a *process*; running it for one company creates an *instance*; and what starts that instance is a *trigger*. You manage all of them in the Back Office under **Administration > Workflows** (shown at the top of this page). | Concept | What it is | |---------|------------| | Process | The workflow itself: a named process bound to a subject type (for example `Company`). It is created once and never replaced — all versions and instances belong to it. | | Version | One complete definition of the process at a point in time (the XML above): its states, transitions, and events, plus the initial state. A process can have many versions, but only one is *active* at a time. | | Trigger | Connects an application event (for example "a company was created") to the process, so that event automatically starts a new instance. | | Instance | One subject running through the workflow — for example one specific company being onboarded. It tracks the subject's current state. | ### Why versions matter Every instance is pinned to the version it started on. When you activate a newer version, running instances do **not** jump to it — they finish on the version they began with. Only *new* instances start on the newly active version. This is what makes editing a live process safe. You publish an improved version for future subjects, while in-flight subjects complete on the exact rules they started with — no half-migrated instances and no transitions that suddenly point at states that no longer exist. ## Subjects A workflow is attached to a *subject type*, which you choose when you create the process. It is not limited to companies: the subject type is a label you define — `Company`, `Customer`, `Product`, or anything your project needs. The trigger you configure decides which application event starts an instance for that subject. For example, a process with subject type `Company` and a trigger on company creation starts one instance per created company, and each company then runs its own instance independently. ## Instances An *instance* is a single subject running through a workflow — for example one specific company being onboarded. Each instance is pinned to the version it started on and tracks its current state. In the Back Office you can inspect instances, see their current state, and trigger any manual actions the workflow defines (for example, a step that a Back Office user must confirm before the workflow continues). {% info_block infoBox "Instance history retention" %} Each instance and its transition history are kept in the database. This MVP does not ship an automated cleanup or retention job, so plan for periodic housekeeping if you expect a high volume of instances. {% endinfo_block %} ## Transitions A workflow advances through three kinds of transitions: - **Event transitions**: triggered by an application event or a manual action in the Back Office. - **Condition transitions**: advance automatically once a business condition becomes true. - **Timeout transitions**: advance automatically after a defined period elapses. Condition and timeout transitions have no incoming event to push them, so two console commands advance them on a schedule: - `workflow:check-condition` — advances every condition transition whose condition has become `true`. - `workflow:check-timeout` — advances every timeout transition whose timeout has elapsed. Without them, an instance that reaches a condition or timeout transition waits forever. These commands are **not** scheduled out of the box; the [installation guide](/docs/dg/dev/integrate-and-configure/integrate-workflow-feature.html) shows how to register them as recurring jobs so workflows progress on their own. ## Triggers A *trigger* connects an application event to a workflow so that a new instance starts automatically. For example, creating a company can trigger a new onboarding instance. You select the trigger event in the Back Office when you configure the process; the available events are provided by trigger plugins (see [Extending a workflow](#extending-a-workflow)). ## Extending a workflow The definition references project code by name in two places: `condition="…"` and `command="…"`. A developer implements each as a plugin and registers it in the project `WorkflowDependencyProvider` (see the [installation guide](/docs/dg/dev/integrate-and-configure/integrate-workflow-feature.html)). The engine matches a plugin to a definition by two values: its `getName()` (the string used in the XML) and its `getSubjectType()` (so the same name can behave differently for different subjects). ### Commands A *command* runs project logic during a transition — for example, marking a company approved when it enters the `approved` state. Reference it in the definition as `command="CompanyOnboarding/MarkCompanyActiveAndApproved"`, then implement `WorkflowCommandPluginInterface` so `getName()` returns that same string: ```php interface WorkflowCommandPluginInterface extends CommandPluginInterface { public function getName(): string; public function getSubjectType(): string; } ``` ### Conditions A *condition* guards a transition: the workflow takes that transition only when the condition returns `true` — for example, "the business is verified." Reference it as `condition="CompanyOnboarding/IsBusinessVerified"`, then implement `WorkflowConditionPluginInterface`: ```php interface WorkflowConditionPluginInterface extends ConditionPluginInterface { public function getName(): string; public function getSubjectType(): string; } ``` ### Trigger plugins A trigger plugin provides an application event that can start an instance. Unlike commands and conditions — which are named inside the definition XML — a trigger is chosen in the Back Office when you configure the process. A trigger plugin binds an application event (`getEventName()`, for example `Entity.spy_company.create`) to a subject type, so that whenever that event fires for that subject, a new instance starts. Implement `StateMachineProcessTriggerPluginInterface`: ```php interface StateMachineProcessTriggerPluginInterface { public function getEventName(): string; public function getName(): string; public function getSubjectType(): string; public function getDescription(): string; } ``` ## Provisioning workflows on installation Workflows can be shipped with a project and provisioned automatically during installation through data import. This means a demo or production workflow is available immediately after setup, and re-importing the same workflow does not create duplicates. See the [installation guide](/docs/dg/dev/integrate-and-configure/integrate-workflow-feature.html) for details.

Keeping dependencies updated for performance

Mon, 14 Sep 2026 13:49:37 +0000

Keeping your project's Spryker module dependencies up to date is critical for maintaining optimal performance, security, and reducing long-term upgrade efforts. ## Why keep dependencies updated Updating dependencies regularly provides several practical benefits: 1. **Risk of security vulnerabilities**: Most recent versions contain necessary fixes to all known vulnerabilities. 2. **Performance and resource consumption optimizations**: Spryker continuously releases performance improvements based on real-life experiences and scenarios. 3. **Decreasing upgrade efforts**: Distributing upgrades across many smaller steps is much easier than doing one massive upgrade later. ## Key resources The following resources provide information about performance-related module releases: - [Security release notes 202512.0](https://docs.spryker.com/docs/about/all/releases/security-releases/security-release-notes-202512.0.html) - [Release notes 202410.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202410.0/release-notes-202410.0.html) - [Release notes 202507.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202507.0/release-notes-202507.0.html) - [General performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) - contains the list of recent module versions with known performance optimizations - [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html) ## Critical module updates The following sections list important module updates that include performance improvements. It's recommended that each Spryker project evaluates and applies these updates. ### Product search performance **spryker/product-page-search** - Recent versions (for example, `3.38.0` - `3.40.0`) include improvements such as: - Caching logic adjustments for product images - Potential bulk operation support to make search document writes more efficient - Avoiding duplicate locale events ### Session management **spryker/session** - at least `^4.17.0` - Provides configurable session locking mechanism - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for configuration details **spryker/session-redis** - at least `^1.11.2` - Includes configurable session locker - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for setup instructions ### Merchant Portal and Back Office performance with ACL rules - [spryker/acl:^3.26.0](https://github.com/spryker/acl/releases/tag/3.26.0) - [spryker/acl-entity:^1.16.0](https://github.com/spryker/acl-entity/releases/tag/1.16.0) - [spryker/gui:^4.11.0](https://github.com/spryker/gui/releases/tag/4.11.0) - [spryker/merchant-profile:^1.9.0](https://github.com/spryker/merchant-profile/releases/tag/1.9.0) - [spryker/merchant-user:^1.9.0](https://github.com/spryker/merchant-user/releases/tag/1.9.0) - [spryker/multi-factor-auth-merchant-portal:^2.1.0](https://github.com/spryker/multi-factor-auth-merchant-portal/releases/tag/2.1.0) - [spryker/product-attribute:^1.18.0](https://github.com/spryker/product-attribute/releases/tag/1.18.0) - [spryker/zed-navigation:^1.15.0](https://github.com/spryker/zed-navigation/releases/tag/1.15.0) ### Back Office performance on category list page - [spryker/product-category:"^4.32.0"](https://github.com/spryker/zed-navigation/releases/tag/4.32.0) ### Order placement performance - [spryker/calculation:^4.14.0](https://github.com/spryker/calculation/releases/tag/4.14.0) - [spryker/discount-calculation-connector:^5.4.0](https://github.com/spryker/discount-calculation-connector/releases/tag/5.4.0) - [spryker/merchant:^3.15.0](https://github.com/spryker/merchant/releases/tag/3.15.0) - [spryker/sales:^11.60.0](https://github.com/spryker/sales/releases/tag/11.60.0) - [spryker/product:^6.49.0](https://github.com/spryker/product/releases/tag/6.49.0) - [spryker/discount:^9.43.0](https://github.com/spryker/discount/releases/tag/9.43.0) - [spryker/product-cart-connector:^4.13.0](https://github.com/spryker/product-cart-connector/releases/tag/4.13.0) - [spryker/company-role:^1.9.1](https://github.com/spryker/company-role/releases/tag/1.9.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) - [spryker/sales-product-connector:^1.11.1](https://github.com/spryker/sales-product-connector/releases/tag/1.11.1) - [spryker/shipment:^8.24.0](https://github.com/spryker/shipment/releases/tag/8.24.0) ### OMS availability check and order item reservation - [spryker/availability:^9.27.0](https://github.com/spryker/availability/releases/tag/9.27.0) - [spryker/stock:^8.10.1](https://github.com/spryker/stock/releases/tag/8.10.1) - [spryker/oms:^11.45.1](https://github.com/spryker/oms/releases/tag/11.45.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) ### Publish and synchronization (merchant-related) - [spryker/merchant-product-offer-storage:^2.6.0](https://github.com/spryker/merchant-product-offer-storage/releases/tag/2.6.0) - [spryker/product-offer-storage:^1.8.0](https://github.com/spryker/product-offer-storage/releases/tag/1.8.0) - [spryker/propel:^3.45.0](https://github.com/spryker/propel/releases/tag/3.45.0) ### Publish and synchronization (merchant relationship prices) - [spryker/merchant:^3.21.0](https://github.com/spryker/merchant/releases/tag/3.21.0) - [spryker/price-product-merchant-relationship:^1.13.0](https://github.com/spryker/price-product-merchant-relationship/releases/tag/1.13.0) - [spryker/price-product-merchant-relationship-storage:^1.22.0](https://github.com/spryker/price-product-merchant-relationship-storage/releases/tag/1.22.0) Additionally, index the `fk_company_business_unit` column of both storage tables. Create `src/Pyz/Zed/PriceProductMerchantRelationshipStorage/Persistence/Propel/Schema/spy_price_product_merchant_relationship_storage.schema.xml` and run `vendor/bin/console propel:install`: ```xml

``` ### Publish and synchronization (product-related) - [spryker/price-product:^4.48.0](https://github.com/spryker/price-product/releases/tag/4.48.0) - [spryker/product-page-search:^3.40.0](https://github.com/spryker/product-page-search/releases/tag/3.40.0) - [spryker/product-search:^5.24.1](https://github.com/spryker/product-search/releases/tag/5.24.1) - [spryker/product-storage:^1.47.0](https://github.com/spryker/product-storage/releases/tag/1.47.0) - [spryker/product-offer-storage:^1.10.0](https://github.com/spryker/product-offer-storage/releases/tag/1.10.0) - [spryker/price-product-offer:^1.7.1](https://github.com/spryker/price-product-offer/releases/tag/1.7.1) - [spryker/price-product-offer-storage:^1.5.1](https://github.com/spryker/price-product-offer-storage/releases/tag/1.5.1) - [spryker/price-product-storage:^4.13.0](https://github.com/spryker/price-product-storage/releases/tag/4.13.0) - [spryker/product-image:^3.20.1](https://github.com/spryker/product-image/releases/tag/3.20.1) - [spryker/product-category-storage:^2.11.0](https://github.com/spryker/product-category-storage/releases/tag/2.11.0) - [spryker/product-category-search:^1.2.1](https://github.com/spryker/product-category-search/releases/tag/1.2.1) - [spryker/propel:^3.47.0](https://github.com/spryker/propel/releases/tag/3.47.0) - Note: If you still use destructive deployments, update the `config/install/destructive.yml` file. You can copy it from any demo shop. - [spryker/event-behavior:^1.32.0](https://github.com/spryker/event-behavior/releases/tag/1.32.0) - [spryker/synchronization-behavior:^1.13.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.13.0) ### Publish and synchronization (Category tree build logic) - [spryker/category:"^5.23.0"](https://github.com/spryker/category/releases/tag/5.23.0) - [spryker/category-storage:"^2.12.0"](https://github.com/spryker/category-storage/releases/tag/2.12.0) - [spryker/propel-orm:"^1.22.0"](https://github.com/spryker/propel-orm/releases/tag/1.22.0) - [spryker/util-sanitize:"^2.3.1"](https://github.com/spryker/util-sanitize/releases/tag/2.3.1) ### Publish and synchronization (queue and event performance) To update all required modules at once: ```bash composer update spryker/rabbit-mq:"^2.25.0" spryker/availability-storage:"^2.11.0" spryker/event:"^2.17.1" spryker/glossary-storage:"^1.14.0" spryker/merchant-product:"^1.12.0" spryker/merchant-product-offer:"^1.12.0" spryker/merchant-product-offer-search:"^1.9.0" spryker/merchant-product-search:"^1.6.0" spryker/merchant-product-storage:"^1.7.0" spryker/price-product:"^4.51.0" spryker/price-product-merchant-relationship-storage:"^1.21.0" spryker/price-product-offer-storage:"^1.8.0" spryker/price-product-storage:"^4.16.0" spryker/product:"^6.54.0" spryker/product-category-search:"^1.3.0" spryker/product-category-storage:"^2.13.0" spryker/product-group-storage:"^1.9.0" spryker/product-image:"^3.21.0" spryker/product-image-storage:"^1.21.0" spryker/product-list:"^1.10.0" spryker/product-list-search:"^2.11.0" spryker/product-list-storage:"^1.21.0" spryker/product-offer:"^1.17.0" spryker/product-offer-availability-storage:"^1.6.0" spryker/product-offer-stock:"^1.7.0" spryker/product-page-search:"^3.47.0" spryker/product-page-search-extension:"^1.7.0" spryker/propel:"^3.50.0" spryker/queue:"^1.28.0" spryker/symfony-messenger:"^1.6.0" spryker/tax-product-storage:"^1.8.0" spryker/url-storage:"^1.23.0" spryker/synchronization-behavior:"^1.14.0" ``` - [spryker/rabbit-mq:^2.25.0](https://github.com/spryker/rabbit-mq/releases/tag/2.25.0) - [spryker/availability-storage:^2.11.0](https://github.com/spryker/availability-storage/releases/tag/2.11.0) - [spryker/event:^2.17.1](https://github.com/spryker/event/releases/tag/2.17.1) - [spryker/event-behavior:^1.35.0](https://github.com/spryker/event-behavior/releases/tag/1.35.0) - [spryker/glossary-storage:^1.14.0](https://github.com/spryker/glossary-storage/releases/tag/1.14.0) - [spryker/merchant-product:^1.12.0](https://github.com/spryker/merchant-product/releases/tag/1.12.0) - [spryker/merchant-product-offer:^1.12.0](https://github.com/spryker/merchant-product-offer/releases/tag/1.12.0) - [spryker/merchant-product-offer-search:^1.9.0](https://github.com/spryker/merchant-product-offer-search/releases/tag/1.9.0) - [spryker/merchant-product-search:^1.6.0](https://github.com/spryker/merchant-product-search/releases/tag/1.6.0) - [spryker/merchant-product-storage:^1.7.0](https://github.com/spryker/merchant-product-storage/releases/tag/1.7.0) - [spryker/price-product:^4.51.0](https://github.com/spryker/price-product/releases/tag/4.51.0) - [spryker/price-product-merchant-relationship-storage:^1.21.0](https://github.com/spryker/price-product-merchant-relationship-storage/releases/tag/1.21.0) - [spryker/price-product-offer-storage:^1.8.0](https://github.com/spryker/price-product-offer-storage/releases/tag/1.8.0) - [spryker/price-product-storage:^4.16.0](https://github.com/spryker/price-product-storage/releases/tag/4.16.0) - [spryker/product:^6.54.0](https://github.com/spryker/product/releases/tag/6.54.0) - [spryker/product-category-search:^1.3.0](https://github.com/spryker/product-category-search/releases/tag/1.3.0) - [spryker/product-category-storage:^2.13.0](https://github.com/spryker/product-category-storage/releases/tag/2.13.0) - [spryker/product-group-storage:^1.9.0](https://github.com/spryker/product-group-storage/releases/tag/1.9.0) - [spryker/product-image:^3.21.0](https://github.com/spryker/product-image/releases/tag/3.21.0) - [spryker/product-image-storage:^1.21.0](https://github.com/spryker/product-image-storage/releases/tag/1.21.0) - [spryker/product-list:^1.10.0](https://github.com/spryker/product-list/releases/tag/1.10.0) - [spryker/product-list-search:^2.11.0](https://github.com/spryker/product-list-search/releases/tag/2.11.0) - [spryker/product-list-storage:^1.21.0](https://github.com/spryker/product-list-storage/releases/tag/1.21.0) - [spryker/product-offer:^1.17.0](https://github.com/spryker/product-offer/releases/tag/1.17.0) - [spryker/product-offer-availability-storage:^1.6.0](https://github.com/spryker/product-offer-availability-storage/releases/tag/1.6.0) - [spryker/product-offer-stock:^1.7.0](https://github.com/spryker/product-offer-stock/releases/tag/1.7.0) - [spryker/product-page-search:^3.47.0](https://github.com/spryker/product-page-search/releases/tag/3.47.0) - [spryker/product-page-search-extension:^1.7.0](https://github.com/spryker/product-page-search-extension/releases/tag/1.7.0) - [spryker/propel:^3.50.0](https://github.com/spryker/propel/releases/tag/3.50.0) - [spryker/queue:^1.28.0](https://github.com/spryker/queue/releases/tag/1.28.0) - [spryker/symfony-messenger:^1.6.0](https://github.com/spryker/symfony-messenger/releases/tag/1.6.0) - [spryker/tax-product-storage:^1.8.0](https://github.com/spryker/tax-product-storage/releases/tag/1.8.0) - [spryker/url-storage:^1.23.0](https://github.com/spryker/url-storage/releases/tag/1.23.0) - [spryker/synchronization-behavior:^1.14.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.14.0) ### Data import (memory usage) - [spryker/acl-entity:"^1.17.0"](https://github.com/spryker/acl-entity/releases/tag/1.17.0) - [spryker/data-import:"^1.33.0"](https://github.com/spryker/data-import/releases/tag/1.33.0) - [spryker/merchant-relationship-product-list-data-import:"^0.1.3"](https://github.com/spryker/merchant-relationship-product-list-data-import/releases/tag/0.1.3) - [spryker/price-product-merchant-relationship-data-import:"^0.2.5"](https://github.com/spryker/price-product-merchant-relationship-data-import/releases/tag/0.2.5) ### Dynamic entity performance improvements - [spryker/dynamic-entity:^1.21.0](https://github.com/spryker/dynamic-entity/releases/tag/1.21.0) - [spryker/dynamic-entity-backend-api:^1.15.0](https://github.com/spryker/dynamic-entity-backend-api/releases/tag/1.15.0) - [spryker/stock:^8.15.0](https://github.com/spryker/stock/releases/tag/8.15.0) ### Cart page and checkout for large carts (100+ items) For comprehensive guidance on optimizing cart performance, see [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html). - [spryker-shop/checkout-page:^3.41.0](https://github.com/spryker-shop/checkout-page/releases/tag/3.41.0) - [spryker-shop/session-customer-validation-page:^1.4.0](https://github.com/spryker-shop/session-customer-validation-page/releases/tag/1.4.0) ### Back Office product abstract list page performance - [spryker/product-management:^0.20.17](https://github.com/spryker/product-management/releases/tag/0.20.17) ### Product detail page performance on Yves - [spryker/currency:^4.9.0](https://github.com/spryker/currency/releases/tag/4.9.0) - [spryker/glossary-storage:^1.15.0](https://github.com/spryker/glossary-storage/releases/tag/1.15.0) - [spryker/kernel:^3.87.0](https://github.com/spryker/kernel/releases/tag/3.87.0) - [spryker/price-product:^4.55.0](https://github.com/spryker/price-product/releases/tag/4.55.0) - [spryker/price-product-storage:^4.18.0](https://github.com/spryker/price-product-storage/releases/tag/4.18.0) - [spryker/product-image-storage:^1.22.0](https://github.com/spryker/product-image-storage/releases/tag/1.22.0) - [spryker/product-storage:^1.58.0](https://github.com/spryker/product-storage/releases/tag/1.58.0) - [spryker/quote:^2.27.0](https://github.com/spryker/quote/releases/tag/2.27.0) - [spryker/redis:^2.14.0](https://github.com/spryker/redis/releases/tag/2.14.0) - [spryker/router:^1.27.0](https://github.com/spryker/router/releases/tag/1.27.0) - [spryker-shop/product-group-widget:^1.14.0](https://github.com/spryker-shop/product-group-widget/releases/tag/1.14.0) - [spryker-shop/product-review-widget:^1.21.0](https://github.com/spryker-shop/product-review-widget/releases/tag/1.21.0) - [spryker-shop/shop-ui:^2.2.0](https://github.com/spryker-shop/shop-ui/releases/tag/2.2.0) - [spryker-shop/store-widget:^1.6.0](https://github.com/spryker-shop/store-widget/releases/tag/1.6.0) - [spryker/store:^1.39.0](https://github.com/spryker/store/releases/tag/1.39.0) - [spryker/synchronization:^1.20.0](https://github.com/spryker/synchronization/releases/tag/1.20.0) - [spryker/url-storage:^1.26.0](https://github.com/spryker/url-storage/releases/tag/1.26.0) ## Update strategy To effectively manage dependency updates: 1. **Monitor release notes**: Regularly check Spryker release notes for performance-related updates. 2. **Test in staging**: Always test module updates in a staging environment before production deployment. 3. **Prioritize performance modules**: Focus on modules that directly impact your application's performance bottlenecks. 4. **Use semantic versioning**: Understand the impact of major, minor, and patch updates. 5. **Batch related updates**: Group related module updates together for testing efficiency. ## Compatibility considerations When updating modules: - Check module compatibility with your current Spryker version - Review breaking changes in major version updates - Test all affected functionality after updates - Monitor application performance metrics before and after updates - Consider using Spryker's [Composer Dependency Manager](https://docs.spryker.com/docs/scos/dev/setup/managing-scos-dependencies-with-composer.html)

Troubleshooting API Platform

Mon, 14 Sep 2026 09:31:15 +0000

This document provides solutions to common issues when working with API Platform in Spryker. ## Generation issues ### Resources not generating **Symptom:** Running `docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate` completes but no resources are created. **Possible causes:** 1. **Schema file location is incorrect** ```bash ❌ src/Pyz/Glue/Customer/api/customers.resource.yml ✅ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml ``` 2. **API type not configured** Check `config/{APPLICATION}/packages/spryker_api_platform.php`: ```php return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void { $sprykerApiPlatform->apiTypes([ 'backend', // Must match directory name ]); }; ``` 3. **Bundle not registered** Verify `config/{APPLICATION}/bundles.php` includes: ```php SprykerApiPlatformBundle::class => ['all' => true], ``` **Solution:** ```bash # Debug to see what's being discovered docker/sdk cli glue api:debug --list # Check schema validation docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only # Force regeneration docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --force ``` ### Schema validation errors **Symptom:** Generation fails with schema validation errors. **Common errors:** ```bash # Error: Invalid operation type ❌ operations: - type: CREATE ✅ operations: - type: Post # Error: Invalid property type ❌ type: int ✅ type: integer # Error: Missing resource name ❌ resource: shortName: customers ✅ resource: name: Customers shortName: customers # Error: Property declares both "items" and "openapiContext.items" # openapiContext is merged on top of the derived schema, so the hand-written # shape would win and the typed element schema would be discarded silently. ❌ categories: type: array items: type: object properties: categoryKey: { type: string } openapiContext: items: type: object properties: categoryKey: { type: string } ✅ categories: type: array items: type: object properties: categoryKey: { type: string } # Error: Property is both a relationship and an inline object list # A relationship property already receives a docblock describing its target # resource, and only one docblock is emitted per property. ❌ includes: - relationshipName: addresses targetResource: CustomersAddresses properties: addresses: type: array items: type: object properties: city: { type: string } ✅ includes: - relationshipName: addresses targetResource: CustomersAddresses ``` **Solution:** 1. Check schema against examples in documentation 2. Use `--validate-only` flag for detailed validation: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only ``` 3. Inspect merged schema: ```bash docker/sdk cli glue api:debug resource-name --show-merged ``` ### A list property still publishes as an untyped array **Symptom:** A `type: array` property has an `items` block, but the published contract shows `"type": "array"` with no `items` reference, and SDK generators produce an untyped collection. **Possible causes:** 1. **`items` is nested under `openapiContext` instead of being a sibling of `type: array`** Only a sibling triggers typing. An `items` block under `openapiContext` is documentation passthrough: it generates no class and produces no reference. ```yaml ❌ categories: type: array openapiContext: items: type: object properties: categoryKey: { type: string } ✅ categories: type: array items: type: object properties: categoryKey: { type: string } ``` 2. **`items.type` is a scalar** A list of scalars generates no element class and no reference. This is expected — there is nothing to type. 3. **The resource was not regenerated after the schema change** ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate ``` 4. **Stale generated code is still being served** See [Inspecting generated code](#inspecting-generated-code) to confirm what is on disk. **Solution:** Confirm the generated resource class carries a `@var array<\Generated\…>` docblock on the property. That docblock is what API Platform reads to build the element reference — if it is absent, the contract falls back to an untyped array. See [Typed collections in the published contract](/docs/integrations/spryker-api/api-platform/typed-collections.html). ## Runtime issues ### Provider/Processor not found **Symptom:** ```bash Error: Class "Pyz\Glue\Customer\Api\Backend\Provider\CustomerBackendProvider" not found ``` **Possible causes:** 1. Class doesn't exist or namespace is wrong 2. Not registered in the Dependency Injection container 3. Typo in the schema file **Solution:** 1. Verify the class exists and namespace matches: ```php namespace Pyz\Glue\Customer\Api\Backend\Provider; class CustomerBackendProvider implements ProviderInterface ``` 2. Ensure services are auto-discovered in `ApplicationServices.php`: ```php $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/'); ``` 3. Check class name in the resource schema file of the module matches exactly: ```yaml provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" ``` ### Validation not working **Symptom:** API accepts invalid data despite validation rules. **Possible causes:** 1. Validation schema file not found 2. Wrong operation name in validation schema 3. Validation groups not matching **Solution:** 1. Ensure validation file exists: ```bash ✅ resources/api/backend/customers.validation.yml ``` 2. Match operation names to HTTP methods: ```yaml post: # For POST /customers email: - NotBlank patch: # For PATCH /customers/{id} email: - Optional: constraints: - Email ``` 3. Check generated resource class (for example `Generated\Api\Storefront\CustomersStorefrontResource`) has validation attributes: ```php #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] public ?string $email = null; ``` ### API documentation UI not displaying correctly **Symptom:** When accessing the root URL of your API application, you see: - Missing styles/CSS - Broken JavaScript functionality - Plain HTML without formatting - "Failed to load resource" errors in the browser console **Cause:** Assets were not installed after API Platform integration. **Solution:** Run the appropriate assets:install command for your application: #### For Glue application ```bash docker/sdk cli glue assets:install public/Glue/assets --symlink ``` #### For GlueStorefront ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue assets:install public/GlueStorefront/assets/ --symlink ``` #### For GlueBackend ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue assets:install public/GlueBackend/assets/ --symlink ``` Then verify the documentation UI loads correctly by visiting the root URL: - Storefront: `https://glue-storefront.mysprykershop.com/` - Backend: `https://glue-backend.mysprykershop.com/` {% info_block warningBox "Required after integration" %} The `assets:install` command must be run after integrating API Platform and whenever API Platform assets are updated. This is a required step documented in [Integrate API Platform](/docs/integrations/spryker-api/migrate-from-glue-to-api-platform/integrate-api-platform.html). {% endinfo_block %} ### 404 Not Found for API endpoints **Symptom:** API requests return 404. **Possible causes:** 1. Router not configured 2. Routes not loaded 3. Wrong URL format **Solution:** 1. Verify `SymfonyFrameworkRouterPlugin` is registered: ```php // RouterDependencyProvider protected function getRouterPlugins(): array { return [ new GlueRouterPlugin(), new SymfonyFrameworkRouterPlugin(), // Must be present ]; } ``` 2. Check API documentation for correct URLs: ```bash Storefront: https://glue-storefront.mysprykershop.com/ Backend: https://glue-backend.mysprykershop.com/ ``` The interactive API documentation is available at the root URL of each application. 3. Use correct URL format: ```bash ❌ /api/v1/customers ✅ /customers ``` ### Every request answers 404 with code 007 or a bare 500, and nothing is logged **Symptom:** A resource that used to work suddenly answers `404` with `{"errors":[{"message":"Not found","status":404,"code":"007"}]}` or a plain `500 Internal Server Error`, the response carries no exception details, and `data/logs` stays empty. **Cause:** The Glue application routes a request to the API Platform kernel only after its own router answered `404`. If the kernel then throws before the router resolved an operation, for example in a `kernel.request` subscriber, an authenticator, or while instantiating one of their dependencies, no exception listener can build a response and the original Glue `404` is sent instead. An exception inside a provider or processor is caught by the API Platform stack and becomes a `500`. In both cases the exception is logged to the container's standard error stream, not to a file. In debug mode the response also carries the exception class, message, file, line, and trace. **Solution:** 1. Read the log of the Glue container, for example: ```bash docker logs spryker_glue_backend_eu_1 --since 5m 2>&1 | grep -i "exception" ``` 2. Enable debug mode for local development. `SPRYKER_DEBUG_ENABLED=1` switches the Glue, Glue Backend, and Glue Storefront kernels into debug mode: the Symfony container is rebuilt when code changes, and exception details are rendered in the response. See [Enable debug mode for the Glue kernels](/docs/integrations/spryker-api/api-platform/configuration.html#enable-debug-mode-for-the-glue-kernels). 3. If the `404` persists in debug mode, the route really is unknown to the API Platform kernel. Regenerate the resources and clear the kernel cache: ```bash docker/sdk cli "GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue api:generate" rm -rf data/cache/GlueBackend/ ``` ### Requests without an `Accept` header are rejected or return the wrong format **Symptom:** A client request that omits the `Accept` header — or sends only `Accept: */*` — returns `406 Not Acceptable`, or a response in a format other than the legacy `application/vnd.api+json`. The legacy Glue REST API silently accepted the same request and answered with `application/vnd.api+json`. **Cause:** API Platform runs content negotiation that requires a satisfiable `Accept` header and does not assume the legacy Glue default. This is a behavioral difference from the legacy Glue REST stack. **Solution:** 1. Upgrade `spryker/api-platform` to **1.15.0 or higher**. Its `AcceptHeaderFallbackSubscriber` restores the legacy behavior — a missing or `*/*` `Accept` header defaults to `application/vnd.api+json`: ```bash composer update spryker/api-platform --with-dependencies ``` 2. If you cannot upgrade, send an explicit `Accept` header from the client: ```bash curl -H "Accept: application/vnd.api+json" https://glue-backend.mysprykershop.com/customers ``` ### Pagination not working **Symptom:** All results returned instead of paginated response. **Solution:** 1. Enable pagination in the schema file of the defining module: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 ``` 2. In the provider, read `page[limit]` and `page[offset]` with `buildPaginationTransfer()`, pass the transfer to the facade, and report the total number of results with `setCollectionPagination()`: ```php $paginationTransfer = $this->buildPaginationTransfer(); $criteriaTransfer->setPagination($paginationTransfer); $collectionTransfer = $this->facade->getCollection($criteriaTransfer); $nbResults = $collectionTransfer->getPagination()?->getNbResults(); if ($nbResults !== null) { $this->setCollectionPagination($paginationTransfer->getOffsetOrFail(), $paginationTransfer->getLimitOrFail(), $nbResults); } ``` 3. Use the JSON:API pagination query parameters: ```bash GET /customers?page[limit]=20&page[offset]=20 ``` A page number parameter such as `page=2` is not supported. If `meta.pagination` is missing from the response, the facade did not return `nbResults` in the collection's `pagination` transfer. ### Client cannot change items per page **Symptom:** The `page[limit]` query parameter is ignored. **Solution:** Enable client-side items-per-page control and set a maximum limit in the resource schema: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 paginationClientItemsPerPage: true paginationMaximumItemsPerPage: 100 ``` Without `paginationClientItemsPerPage: true`, the `itemsPerPage` query parameter has no effect. The `paginationMaximumItemsPerPage` option prevents clients from requesting excessively large pages. ### Client cannot disable pagination **Symptom:** The `pagination=false` query parameter is ignored and results are still paginated. **Solution:** Enable client-side pagination control in the resource schema: ```yaml resource: paginationClientEnabled: true ``` Without `paginationClientEnabled: true`, the `pagination` query parameter has no effect. For a full reference of all pagination options, see [Resource schemas — Pagination](/docs/integrations/spryker-api/api-platform/resource-schemas.html#pagination). ## Dependency Injection issues ### Services not autowired **Symptom:** ```bash Cannot autowire service "CustomerBackendProvider": argument "$customerFacade" references class "CustomerFacadeInterface" but no such service exists. ``` **Solution:** 1. Register facade in the respective applications `ApplicationServices.php`: ```php use Pyz\Zed\Customer\Business\CustomerFacadeInterface; use Pyz\Zed\Customer\Business\CustomerFacade; $services->set(CustomerFacadeInterface::class, CustomerFacade::class); ``` 2. Ensure constructor uses interface type hints: ```php public function __construct( private CustomerFacadeInterface $customerFacade, // ✅ Interface ) {} ``` ## Performance issues ### Slow API responses **Symptom:** API endpoints respond slowly. **Solution:** 1. Verify that Opcache is enabled (`opcache.enable: 1`). Without it, PHP recompiles the whole application on every request, which adds a flat overhead of seconds to every endpoint regardless of the amount of data. See [Opcache activation](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html#opcache-activation). 2. Enable Symfony cache: ```bash docker/sdk cli glue cache:warmup ``` 3. Use pagination for collections 4. Optimize database queries in Provider 5. Use API Platform's built-in caching features ## Development tips ### Debugging schema merging See which schemas contribute to final resource: ```bash docker/sdk cli glue api:debug customers --api-type=backend --show-sources ``` Output: ```bash Source Files (priority order): ✓ vendor/spryker/customer/resources/api/backend/customers.resource.yml (CORE) ✓ src/SprykerFeature/CRM/resources/api/backend/customers.resource.yml (FEATURE) ✓ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml (PROJECT) ``` ### Inspecting generated code View the generated resource class: ```bash cat src/Generated/Api/Backend/CustomersBackendResource.php ``` Check for: - Correct property types - Validation attributes - API Platform metadata ### Testing with dry-run Preview generation without writing files: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --dry-run ``` ## Getting help If you encounter issues not covered here: 1. **Check logs:** ```bash tail -f var/log/application.log tail -f var/log/exception.log ``` 2. **Enable debug mode:** ```php debug(true); }; ``` 3. **Validate environment:** ```bash php -v # Check PHP version (8.3+) composer show | grep api-platform docker/sdk cli glue debug:container | grep -i api ``` 4. **Common error patterns:** | Error | Likely cause | Solution | |-------|--------------|----------| | `Class not found` | Autoloading issue | Run `composer dump-autoload` | | `Service not found` | DI configuration | Check `ApplicationServices.php` | | `Route not found` | Router not configured | Add `SymfonyFrameworkRouterPlugin` | | `Validation failed` | Schema mismatch | Regenerate with `--force` | | `Cache is stale` | Outdated cache | Run `cache:clear` | | API docs UI broken/unstyled | Assets not installed | Run `docker/sdk cli glue assets:install` |

API Platform configuration

Mon, 14 Sep 2026 09:31:15 +0000

This page is the canonical reference for all API Platform configuration in Spryker. API Platform is configured through two PHP config files per application: the native api_platform.php (API Platform’s own options, with Spryker adaptations for PHP-based configuration and environment control) and Spryker’s spryker_api_platform.php (which drives schema generation). Both are documented below.

Configuration file locations

Each application layer carries two configuration files:

Application	Native API Platform config	Spryker generator config
Glue	`config/Glue/packages/api_platform.php`	`config/Glue/packages/spryker_api_platform.php`
GlueStorefront	`config/GlueStorefront/packages/api_platform.php`	`config/GlueStorefront/packages/spryker_api_platform.php`
GlueBackend	`config/GlueBackend/packages/api_platform.php`	`config/GlueBackend/packages/spryker_api_platform.php`

api_platform.php configures API Platform itself (Swagger, formats, pagination defaults, resource mapping paths). Documented under Native API Platform configuration below.
spryker_api_platform.php configures Spryker’s schema generator (which API types an application serves, where schemas are scanned, which modules stay on Glue). Documented under Resource generation configuration below.

Released configuration reference

The simplest starting point is a real, released configuration. The links below point to the B2B Demo Marketplace at release release-202604.0; check newer releases for updates.

Application	`api_platform.php`	`spryker_api_platform.php`
Glue	api_platform.php	spryker_api_platform.php
GlueStorefront	api_platform.php	spryker_api_platform.php
GlueBackend	api_platform.php	spryker_api_platform.php

Resource generation configuration (spryker_api_platform.php)

spryker_api_platform.php controls Spryker’s API Platform schema generator — it is separate from the native api_platform.php. Create one in each application layer where you enable API Platform. The files share the same shape; they differ only in apiTypes() and in the modules each application still serves via Glue.

Three settings:

apiTypes() — the API types this application serves: ['storefront'] for the Glue and GlueStorefront applications, ['backend'] for the GlueBackend application.
sourceDirectories() — where the generator scans for API Platform schemas. Optional; defaults to src/Spryker, src/SprykerFeature, and src/Pyz. Set it only if your schemas live somewhere else.
excludedPathFragments() — schema paths the generator skips. Use it to keep a module’s API Platform schemas hidden from the generator (for example, a module the project still serves via Glue). Each entry is matched as a substring of the full schema path.

excludedPathFragments does not switch routing

excludedPathFragments controls only what the schema generator emits. It does not flip routing. A module stays on Glue as long as its *ResourceRoutePlugin is registered in the project dependency provider. See Step 3 — Batch migration in the migration overview.

config/Glue/packages/spryker_api_platform.php (storefront example):

<?php

declare(strict_types = 1);

use Symfony\Config\SprykerApiPlatformConfig;

return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['storefront']);

    // Keep these modules on the Glue REST stack by hiding their API Platform schemas from the generator.
    $sprykerApiPlatform->excludedPathFragments([
        'vendor/spryker/customer/src/Spryker/Customer/resources/api/',
        'vendor/spryker/store/src/Spryker/Store/resources/api/',
        'vendor/spryker/authentication/src/Spryker/Authentication/resources/api/',
    ]);
};

For the GlueBackend application, set apiTypes(['backend']) and list the modules that application still serves via Glue in excludedPathFragments().

Native API Platform configuration (api_platform.php)

api_platform.php configures API Platform itself. Spryker ships working defaults, so most projects only adjust a few options. The sections below cover the Spryker-specific adaptations and the settings you are most likely to change.

Spryker-specific differences

PHP configuration instead of YAML

Spryker uses PHP configuration with Symfony’s type-safe configuration objects instead of YAML files:

use Symfony\Config\ApiPlatformConfig;

return static function (ApiPlatformConfig $apiPlatform, string $env): void {
    // Configuration here
};

Environment variable for conditional settings

The configuration function receives an $env parameter for environment-specific behavior.

Common environment values: prod, dev, dockerdev, test

For a full example, see Enable the documentation UI only in development.

Configuration examples

Enable the documentation UI only in development

By default, Spryker shows the documentation UI (Swagger UI) only in development environments. You can configure this behavior based on the $env parameter:

return static function (ApiPlatformConfig $apiPlatform, string $env): void {
    // Enable developer tools only in development
    if ($env === 'dockerdev') {
        $apiPlatform->enableSwagger(true);
        $apiPlatform->enableSwaggerUi(true);
        $apiPlatform->enableReDoc(true);
        $apiPlatform->enableDocs(true);
    }
};

Enable debug mode for the Glue kernels

The Symfony kernel of each Glue application takes its debug flag from the application’s own configuration constant, not from APPLICATION_ENV. The Docker dev configuration wires all three to the SPRYKER_DEBUG_ENABLED environment variable:

// config/Shared/config_default-docker.dev.php
$config[GlueApplicationConstants::ENABLE_APPLICATION_DEBUG]
    = $config[GlueBackendApiApplicationConstants::ENABLE_APPLICATION_DEBUG]
    = $config[GlueStorefrontApiApplicationConstants::ENABLE_APPLICATION_DEBUG]
    = (bool)getenv('SPRYKER_DEBUG_ENABLED');

With debug enabled, the Symfony container is rebuilt when a resource, provider, or configuration file changes, the API Platform error renderer includes the exception message and trace in error responses, and spryker_api_platform.debug follows %kernel.debug%. With debug disabled, uncaught exceptions are reduced to a generic 500 and are only visible in the container log.

Disable Doctrine integration

Spryker does not use Doctrine with API Platform:

$apiPlatform->doctrine()->enabled(false);
$apiPlatform->doctrineMongodbOdm()->enabled(false);

Configure resource mapping paths

Specify where API Platform discovers resource classes. By default, only the generated resource directory is configured:

$apiPlatform->mapping()->paths([
    '%kernel.project_dir%/src/Generated/Api/Backend'
]);

Add custom resource paths

To use native API Platform resources alongside generated resources, add your directories to the mapping paths:

$apiPlatform->mapping()->paths([
    '%kernel.project_dir%/src/Generated/Api/Backend',
    '%kernel.project_dir%/src/Pyz/Glue/*/Api/Backend/Resource',
]);

API Platform scans all configured paths for PHP classes with #[ApiResource] attributes. Generated and manually created resources coexist without conflict.

Keep the generated path

Always keep the src/Generated/Api/{ApiType} path in the list. Removing it disables all YAML-generated resources.

For a complete guide on creating native resources, see Native API Platform resources.

Set pagination defaults

$apiPlatform->defaults()->paginationItemsPerPage(10);

$apiPlatform->collection()
    ->pagination()
        ->pageParameterName('page')
        ->itemsPerPageParameterName('itemsPerPage');

These global defaults apply to all resources. Individual resources can override pagination behavior using per-resource options such as paginationEnabled, paginationItemsPerPage, paginationMaximumItemsPerPage, paginationClientEnabled, and paginationClientItemsPerPage in their YAML schema files. See Resource schemas — Pagination for details.

Configure supported formats

$apiPlatform->formats('jsonapi', ['mime_types' => ['application/vnd.api+json']]);
$apiPlatform->formats('jsonld', ['mime_types' => ['application/ld+json']]);
$apiPlatform->formats('xml', ['mime_types' => ['application/xml']]);

Configure security

Security is configured in a separate security.php file. For details, see Integrate API Platform security.

Complete configuration reference

For all available configuration options and their details, refer to the API Platform Symfony Configuration documentation.

The PHP method names in ApiPlatformConfig correspond directly to the YAML keys in the official documentation.

Resource schemas

Fri, 11 Sep 2026 08:04:21 +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. A variant keeps the same file name as the base schema but lives in a separate variant module directory—for example, `StoresApiEU`—and sets the `codeBucket:` property inside the schema file. The generator produces one class per variant following the `{ResourceName}{CodeBucket}{ApiType}Resource` pattern, and the base resource is used when no matching variant exists. For file naming, class naming, URL behavior, and implementation examples, see [CodeBucket support](/docs/integrations/spryker-api/api-platform/code-buckets.html). ## Resource schema syntax ### Minimal example ```yaml resource: name: Products shortName: products description: "Product resource" operations: - type: Get - type: GetCollection properties: id: type: integer writable: false identifier: true name: type: string ``` {% info_block infoBox "shortName convention" %} `shortName` is the JSON:API `type` field for the resource and is used as the public URL segment. Use **lowercase kebab-case**, plural for noun-style resources (`products`, `addresses`, `abstract-product-prices`) and singular for action-style endpoints (`catalog-search`, `cart-reorder`). Multi-word names are always hyphenated. This matches every shipped resource in the platform. {% endinfo_block %} ### Complete example with all options ```yaml # yaml-language-server: $schema=../../../../../vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json resource: # Resource identification name: Customers # Internal name (used for schema merging) shortName: customers # URL name (becomes /customers); JSON:API type field 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 # JSON:API `included` array ordering — see "Sort priority for included resources" includedSortPriority: 0 # 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 # Relationships — see Relationships article for full reference includes: - relationshipName: addresses targetResource: CustomersAddresses uriVariableMappings: customerReference: customerReference # 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. Add an `items` sibling to publish a typed element schema instead of an untyped array — see [Object collections](#object-collections) and [Typed collections in the published contract](/docs/integrations/spryker-api/api-platform/typed-collections.html). | | `object` | `object` | `{"key": "value"}` | Strictly typed nested objects — generates a typed companion class. See [Typed nested objects](#typed-nested-objects). A project can also share one shape across resources with a [canonical nested object](#project-defined-canonical-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 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. When you do want a strongly typed class for the payload — so PHP enforces the field set and the OpenAPI document publishes a named component schema — use `type: object` with nested `properties:` instead. See [Typed nested objects](#typed-nested-objects). ### 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 ``` ## Typed nested objects A property declared as `type: object` with its own nested `properties:` block generates a dedicated, strongly typed companion class — not an untyped array. The generator emits one PHP class per nested object, types the parent property to that class, and publishes a full field-by-field schema in the OpenAPI document. The serializer hydrates the nested object from the same JSON payload, so the response on the wire is identical to the array-based form it replaces. This is the strongly typed counterpart to the `map` pattern described in [Documenting nested properties for OpenAPI and Swagger UI](#documenting-nested-properties-for-openapi-and-swagger-ui): `map` documents a nested object while keeping it a plain PHP `array`; `type: object` promotes it to a real class whose shape is enforced by PHP's type system. ### Why use it - **Type safety in PHP.** The parent property is typed to the generated class (for example, `?CartsTotalsStorefrontObject`) instead of `array`, so providers and processors get IDE autocompletion and the language enforces the field set. - **Precise OpenAPI schema.** Each sub-field carries its own `type`, `description`, and `example`, so the OpenAPI document and Swagger UI render the object as a named component schema instead of an opaque `object`. - **No runtime contract change.** Because the serializer denormalizes the typed object from the same keys, migrating a property from `array`/`map` to `type: object` leaves the JSON response unchanged — only the generated PHP and the published schema improve. ### When to use which type | Use | When | |-----|------| | `type: object` (with `properties`) | The payload has a **stable, known shape** you want enforced as a PHP class — for example, cart and order `totals`, or a quote-request `customer`. | | `type: map` (with `openapiContext`) | The shape is known and worth documenting, but you do **not** want a dedicated PHP class — for example, payloads aggregated from several transfer objects, or PSP-specific responses. See [Documenting nested properties for OpenAPI and Swagger UI](#documenting-nested-properties-for-openapi-and-swagger-ui). | | `type: mixed` | The payload genuinely has **no fixed shape** and cannot be described via `openapiContext`. | ### How to declare it Give the property `type: object` and nest its fields under `properties:`. Sub-fields accept the same attributes as top-level properties (`type`, `description`, `openapiContext`, `nullable`, `serializedName`, `serializedPath`): ```yaml totals: type: object readable: true writable: false required: false description: 'Calculated cart totals in cents.' properties: subtotal: type: integer description: 'Items × prices before any discount/tax.' openapiContext: { example: 16058 } grandTotal: type: integer description: 'What the customer pays.' openapiContext: { example: 14601 } priceToPay: type: integer description: 'Grand total adjusted for any pre-paid amount (e.g. gift cards).' openapiContext: { example: 14601 } ``` ### Generated output For a `Carts` resource with the `totals` property above, the generator: 1. Types the property on the resource class: ```php public ?CartsTotalsStorefrontObject $totals = null; ``` 2. Writes a companion class in the `Generated\Api\{ApiType}\{ResourceName}\` namespace (a sub-namespace named after the owning resource, alongside the resource class in `Generated\Api\{ApiType}\`). The class is `final`, carries **no** `#[ApiResource]` attribute — it is an embedded value object, not a routed resource — and exposes the typed sub-fields plus their accessors: ```php namespace Generated\Api\Storefront\Carts; use ApiPlatform\Metadata\ApiProperty; final class CartsTotalsStorefrontObject { #[ApiProperty(description: 'Items × prices before any discount/tax.', openapiContext: ['example' => 16058])] public ?int $subtotal = null; #[ApiProperty(description: 'What the customer pays.', openapiContext: ['example' => 14601])] public ?int $grandTotal = null; #[ApiProperty(description: 'Grand total adjusted for any pre-paid amount (e.g. gift cards).', openapiContext: ['example' => 14601])] public ?int $priceToPay = null; // Getters, setters, toArray(), fromArray() … } ``` The companion class name is `{ResourceName}{PropertyPath}{ApiType}Object` — the resource's normalized name, the capitalized property path, the API type, and the `Object` suffix (contrast the routed resource class itself, which keeps the `Resource` suffix). It lives in the `Generated\Api\{ApiType}\{ResourceName}` sub-namespace. So `Carts` + `totals` on the storefront API becomes `Generated\Api\Storefront\Carts\CartsTotalsStorefrontObject`; a checkout `billingAddress` becomes `Generated\Api\Storefront\Checkout\CheckoutBillingAddressStorefrontObject`. {% info_block infoBox "Imports in companion classes" %} Companion classes import only the attributes they actually use (`ApiProperty`, `SerializedName`, `SerializedPath`). An attribute referenced without its `use` statement would resolve to a non-existent class in the `Generated` namespace and break attribute reflection at runtime, so the generator never emits an unused import. {% endinfo_block %} ### Nested objects within objects Objects can nest to any depth. Each level generates its own class, named by concatenating the property path onto the resource name. For example: ```yaml totals: type: object properties: tax: type: object properties: amount: type: integer description: 'Tax amount in cents.' openapiContext: { example: 1457 } ``` on the storefront `Carts` resource generates a `CartsTotalsStorefrontObject` class with `public ?CartsTotalsTaxStorefrontObject $tax = null;`, plus a separate `CartsTotalsTaxStorefrontObject` class with `public ?int $amount = null;` (both in the `Generated\Api\Storefront\Carts` namespace). A deeper path simply keeps concatenating — an agent quote-request resource's `shownVersion.cartTotals` object becomes `AgentQuoteRequestsShownVersionCartTotalsStorefrontObject`. ### Object collections A `type: array` property whose `items:` are themselves a typed object (`type: object` with nested `properties:`) generates a value-object class for the element type. The class is named after the **pluralized** field segment — `{ResourceName}{PluralField}{ApiType}Object` — and the parent property stays a PHP `array` carrying a `@var array<…>` docblock so the serializer denormalizes each element into the generated class: ```yaml # carts.resource.yml — a list of typed customer objects customer: type: array items: type: object properties: firstName: { type: string } email: { type: string } ``` On the storefront `Carts` resource this generates `CartsCustomersStorefrontObject` (the field `customer` pluralized to `Customers`) as the element type, and types the property as `array<\Generated\Api\Storefront\Carts\CartsCustomersStorefrontObject>`. In the published contract, the property becomes `"type": "array"` with an `items` reference to the generated element schema, which API Platform registers in the same document. Without an `items` block, the property publishes as a bare array with no element description. {% info_block warningBox "Typing an existing list is a backward-compatibility decision" %} Generated value objects copy only the fields you declare, so adding an `items` block to a list that is already part of a released response silently drops every payload key missing from `items.properties`. Check a real payload first — see [Typed collections in the published contract](/docs/integrations/spryker-api/api-platform/typed-collections.html). {% endinfo_block %} ### Per-resource validation lifting Each typed nested object gets its **own** value-object class, so validation you authored the array-shaped way — an `Assert\Collection` on the object property in the resource's `{resource-name}.validation.yml` — would reject the denormalized object value with a 422 (`This value should be of type array`). The generator resolves this automatically: for a writable object property it **lifts** the `Collection.fields` constraints off the property and onto the matching fields of that resource's value object, and emits a plain `#[Assert\Valid]` cascade (carrying the operation groups) on the property instead of the `Collection`. You keep authoring validation exactly as before — write the `Collection` against the object property: ```yaml # checkout-data.validation.yml post: customer: - Optional: constraints: - Collection: allowExtraFields: true fields: email: - NotBlank: { message: 'Email is invalid.' } - Email: { message: 'Email is invalid.' } ``` The lifted constraints are re-grouped through the resource's own operation groups (so this `checkout-data` `customer.email` rule stays in the `checkout-data:create` group) and attached to the value object's `email` field; the `customer` property itself carries only `#[Assert\Valid]`. Each resource's value object is validated independently — there is **no** cross-resource union, because every resource has its own value-object class. A property whose object is not writable, or a plain list property that is not a typed object collection, keeps its array-shaped `Collection` — only writable typed-object properties are lifted. #### `allowMissingFields` A `Collection` with `allowMissingFields: true` (for example, a checkout `billingAddress` referenced only by id) tolerates absent keys. On a value object an absent field denormalizes to `null`, so the generator relaxes presence constraints when lifting: each `NotBlank` gains `allowNull: true` and each `NotNull` is dropped — an absent field passes, a present-but-empty one still fails. ### Cross-module field contribution Because each resource owns its value-object class, a nested object's fields can still be contributed from several modules — this is how you keep the dependency direction correct, with each field declared in its owning module. Multiple modules ship a same-named `*.resource.yml` fragment for the same resource, and the schema merger **deep-merges nested object `properties`** (and `items.properties` for collections) rather than letting a later fragment's nested block replace an earlier one. For example, both `DiscountsRestApi` and `ProductOptionsRestApi` add fields to the cart-items `calculations` object: ```yaml # DiscountsRestApi — cart-items.resource.yml resource: name: CartItems properties: calculations: type: object properties: discountTotal: { type: integer } # ProductOptionsRestApi — cart-items.resource.yml resource: name: CartItems properties: calculations: type: object properties: productOptionTotal: { type: integer } ``` The merged `calculations` object carries **both** `discountTotal` and `productOptionTotal`, and a single `CartItemsCalculationsStorefrontObject` value object is generated for it. This deep merge — not a shared class — is how identically-named objects accumulate fields across modules while each resource keeps its own independent request/response shape. #### Conflicting shapes fail generation Deep merge only applies when the contributors agree on the shape. When one contributor declares a property as a typed object (`type: object` with `properties`) or an object collection (`type: array` with `items.properties`) and another declares the **same** property as something structurally different — a `map`, a scalar, a plain array, or an object without `properties` — a silent last-wins merge would drop either the typed value object or the plain field. Instead, generation **fails with an error** that names the property and both contributing source files: ```text Conflicting shapes for property "calculations": .../DiscountsRestApi/.../cart-items.resource.yml declares it as a typed object (`type: object` with `properties`), but .../project/.../cart-items.resource.yml declares it as `type: map`. ... ``` This applies both within a layer and across layers (project overrides feature overrides core). The usual cause is a project fragment that still declares a property as `type: map`/`array` while a core module has since promoted it to a typed object — convert the project fragment to the typed form. Same-shape overrides (object + object, collection + collection) still deep-merge, and attribute-only overrides (an override that sets, for example, `writable: false` without re-declaring `type`) merge as before. If you deliberately intend to re-shape an inherited property — for example, collapse a core typed object back into a `map`, or replace it wholesale rather than extend it — set `replace: true` on the overriding declaration. It takes your declaration wholesale (the inherited one is discarded), suppresses the conflict guard, and is stripped from the generated output: ```yaml # project cart-items.resource.yml — deliberately override the core shape calculations: type: map replace: true ``` ## Project-defined canonical nested objects [Typed nested objects](#typed-nested-objects) generate one value-object class **per resource property**: a `billingAddress` on the checkout resource and a `shippingAddress` on the order resource each get their own independent class, even when both describe the same real-world shape. That keeps each resource self-contained, but it also means the same address shape is authored and maintained in several places. A **canonical nested object** lets a project define that shared shape **once** and have it flow into every resource property that opts in. All the opting-in properties then collapse onto a single generated class — `Generated\Api\{ApiType}\{Object}` (for example, `Generated\Api\Storefront\Address`) — instead of a per-resource companion class. This is a pure project opt-in. With no canonical object files present, generation is byte-for-byte identical to the default per-resource behavior described above — nothing changes until a project adds its first `*.object.yml`. ### File location and naming Canonical objects live in a **dedicated, reserved subdirectory literally named `objects/`** inside the per-`apiType` resource directory. The directory name is always `objects` — it is never named after a resource or module. This is distinct from resource definition files, which live directly in the `apiType` directory: ```text resources/api/storefront/ ├── checkout.resource.yml # a resource definition ├── checkout.validation.yml # its validation └── objects/ # reserved dir — canonical objects only ├── address.object.yml └── address.object.validation.yml ``` Only `*.object.yml` and `*.object.validation.yml` files belong in `objects/`. Resource files (`*.resource.yml`) are placed directly in the per-`apiType` directory, never inside `objects/`. The `..yml` naming pattern is the same for both file types — only the kind word differs. `address.object.yml` is the canonical-object analog of `checkout.resource.yml`, and `address.object.validation.yml` is the analog of `checkout.validation.yml`. The `object` versus `resource` word identifies the artifact kind, not a different naming scheme. Full path patterns: ```text resources/api//objects/.object.yml resources/api//objects/.object.validation.yml # optional, see Validation ``` For example, on the storefront API: ```text src/Pyz/resources/api/storefront/objects/address.object.yml src/Pyz/resources/api/storefront/objects/address.object.validation.yml ``` The file name uses a dashed (kebab-case) object name, while `object.name` **inside** the file is CamelCase. The CamelCase `object.name` is the contract: it must exactly match the `objectName:` join tag declared on the resource properties that want this shape (see [The `objectName` join tag](#the-objectname-join-tag)). ### Central directory A project may keep canonical object files in one central location instead of (or in addition to) the per-module `objects/` directories. Both locations are scanned simultaneously. Configure the central directory via the Symfony bundle config node `spryker_api_platform.canonical_object_search_directories`, keyed by API type. Relative paths resolve against the project root; `%kernel.project_dir%` is also supported: ```yaml # config/packages/spryker_api_platform.yaml spryker_api_platform: canonical_object_search_directories: storefront: - '%kernel.project_dir%/config/api/objects/storefront' ``` The same `*.object.yml` / `*.object.validation.yml` naming rules apply. Files in a central directory are always treated as the **project** layer, so they participate in the standard `project > feature > core` merge precedence. Defining the same `objectName` more than once within the same layer — for example, one module file and one central-directory file both at project layer — is a fail-loud error: generation aborts with an `ApiSchemaGenerationException` naming both source files. The same name across different layers is fine — that is the normal override. ### File format The file contains a single top-level `object:` key: ```yaml # address.object.yml object: name: Address # CamelCase; matches `objectName: Address` on resource properties properties: salutation: { type: string, description: 'Address salutation.', example: 'Mr' } firstName: { type: string, description: 'First name.', example: 'Jane' } lastName: { type: string, description: 'Last name.', example: 'Doe' } address1: { type: string, description: 'Street name.', example: 'Julie-Wolfthorn-Straße' } zipCode: { type: string, description: 'ZIP / postal code.', example: '10115' } city: { type: string, description: 'City.', example: 'Berlin' } ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `object.name` | string | Yes | CamelCase object name. Matched against `objectName:` join tag on every resource property that references this object. | | `object.properties` | map | Yes | Field definitions. Each field uses the **same syntax as a resource property** — `type`, `description`, `validation`, `example`, and so on. | | `object.extends` | string | No | CamelCase name of another canonical object whose resolved fields are inherited first. See [Composition](#composition-with-extends-and-omit). | | `object.omit` | string[] | No | Names of inherited fields to drop from the `extends` base before this object's own properties are applied. | ### Composition with `extends` and `omit` An object can inherit another canonical object's fields with `extends`, then trim and extend them. This avoids re-declaring a shared shape when one variant is a near-copy of another — for example, a read-only address snapshot derived from a writable address: ```yaml # address-snapshot.object.yml object: name: AddressSnapshot extends: Address # inherit all Address fields first omit: [id, idCompanyBusinessUnitAddress] # drop the write-only identifiers properties: country: { type: string, description: 'Country name.', example: 'Germany' } # add a read-only field ``` Fields resolve in this order, with later steps winning: 1. The fields inherited from `extends`. 2. Any field named in `omit` is removed. 3. This object's own `properties` are applied — a field redeclared here overrides the inherited one. An `extends` cycle (for example, two objects that extend each other) is rejected at generation time with an `ApiSchemaGenerationException`. ### The `objectName` join tag A resource property opts into a canonical object by declaring `type: object` together with an `objectName:` tag whose value equals the canonical `object.name`: ```yaml # checkout.resource.yml properties: billingAddress: type: object objectName: Address # joins this property to the canonical Address object readable: false writable: true properties: zipCode: { type: string } ``` The `objectName` tag is dormant on its own: if no `address.object.yml` exists, the property's inline `properties:` block is generated exactly as a normal [typed nested object](#typed-nested-objects). When a canonical file for `Address` **is** present, the tag activates and: - The property's inline `properties:` are **replaced** by the canonical object's resolved shape. - The mount attributes — `readable`, `writable`, `required`, `nullable` — stay on the referencing property. They describe how this property is mounted on this resource and are **not** owned by the canonical object, so the same canonical shape can be writable on one resource and read-only on another. - A single shared `Generated\Api\{ApiType}\{Object}` class is emitted for the canonical object. No per-property companion class is generated for that property; every property tagged with the same `objectName` is typed to the one shared class. {% info_block infoBox "Shared class versus per-resource class" %} Without `objectName`, each `type: object` property generates its own per-resource value-object class (for example, `CheckoutBillingAddressStorefrontObject`). With `objectName: Address`, all matching properties across all resources instead share the single `Generated\Api\Storefront\Address` class. Use a canonical object when several resources genuinely share one shape and you want them to stay in lockstep; keep the inline form when each resource's shape is independent. {% endinfo_block %} ### Validation Field-level validation for a canonical object is authored in a parallel `.object.validation.yml` file, using the same format as a resource [validation schema](/docs/integrations/spryker-api/api-platform/validation-schemas.html): ```yaml # address.object.validation.yml zipCode: - NotBlank: { message: 'ZIP code is required.' } firstName: - NotBlank: { message: 'First name is required.' } ``` These constraints are lifted onto the generated canonical class. Every resource property that references the object through `objectName` then carries an `Assert\Valid` cascade to that class, so the canonical field rules are enforced wherever the object is used — you author the object's validation once, in one place. ### Layer precedence Canonical objects follow the same layer rules as resource schemas. The layer is detected from the file path — a `/Pyz/` path is a project file, a `/SprykerFeature/` path is a feature file, and anything else is core. Same-named objects merge by `object.name` with the precedence: ```text project > feature > core ``` Because the merge is by `objectName`, a project can add a single field to a feature-layer canonical object without redefining the whole object. Core ships no canonical object files today; the mechanism is available to the project, feature, and core layers, and in practice projects are the primary users. ## 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/integrations/spryker-api/api-platform/validation-schemas.html). ## Automatic JSON:API request body examples For JSON:API endpoints (`application/vnd.api+json`), the generator automatically wraps property-level examples in the JSON:API envelope (`data.type` + `data.attributes`) when it builds the OpenAPI request body. You define examples once per property; the generator assembles the envelope for every write operation. Given: ```yaml resource: name: Customers shortName: customers # becomes the JSON:API "type" field properties: email: type: string writable: true openapiContext: example: "john@example.com" firstName: type: string writable: true openapiContext: example: "John" idCustomer: type: integer writable: false # excluded from request body example openapiContext: example: 42 ``` …the generated OpenAPI request body for `POST`, `PATCH`, and `PUT` operations is: ```json { "data": { "type": "customers", "attributes": { "email": "john@example.com", "firstName": "John" } } } ``` Rules the generator applies: - The `shortName` value becomes the `type` field. - Only **writable** properties are included — anything marked `writable: false` is filtered out (so identifiers and timestamps do not appear in the request example). - Properties without an `openapiContext.example` are omitted from the example body. - If no writable property has an example, no `requestBody` example is emitted at all — the operation appears without a prefilled "Try Out" body. If you need a custom request body example that does not match this shape, override it at the operation level — see [Operations](#operations). ## 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) ### Operation options Each operation entry accepts the following optional keys: | Key | Description | |-----|-------------| | `name` | Operation name used in the generated attribute. Required when a resource has several operations of the same type. | | `uriTemplate` | Custom URL path for the operation. See [Custom URL paths](#custom-url-paths). | | `description` | Prose shown for the operation in Swagger UI. | | `openapiContext` | OpenAPI details for the operation: `summary`, `parameters`, `responses`, and a custom `requestBody` example. | | `openapi` | Set to `false` to keep the route but hide the operation from the OpenAPI document and Swagger UI. | | `security`, `securityMessage` | Operation-level security expression. See [Security expressions](#security-expressions). | #### Documenting query parameters Query parameters that a provider reads, such as `sort`, `filter[.]`, or `q`, are not derived from the resource properties. Declare each of them under `openapiContext.parameters` so that it appears as an input field in Swagger UI. Use `schema.enum` for closed value sets, for example the supported sort fields. ```yaml operations: - type: GetCollection description: 'List categories.' openapiContext: summary: 'Retrieve the category collection' parameters: - name: sort in: query required: false description: 'Sort field. Prefix with `-` for descending order.' schema: type: string enum: [categoryKey, -categoryKey, position, -position, name, -name] example: -position - name: parentCategoryKey in: query required: false description: 'Return only the direct children of this category.' schema: type: string example: computer responses: 200: description: 'Category collection.' ``` Do not declare `page[limit]` and `page[offset]`: they are added to every paginated collection operation automatically. See [Pagination](#pagination). #### Hiding an operation from the documentation Some operations exist only to answer legacy URL shapes with a `400` or `501` error, for example `GET /abstract-products/abstract-product-prices` next to the real `GET /abstract-products/{sku}/abstract-product-prices`. Mark them with `openapi: false`. The route keeps working, but Swagger UI does not list the operation as an endpoint. ```yaml operations: - type: GetCollection name: getAbstractProductPricesBare uriTemplate: /abstract-products/abstract-product-prices description: 'Returns 400 when called without the abstract product SKU.' openapi: false ``` ## 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 the `page[limit]` query parameter. Larger values are clamped to this maximum. | | `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 `page[limit]` query parameter. | Spryker resources use the JSON:API offset pagination parameters `page[limit]` and `page[offset]`. The OpenAPI document exposes these two parameters on every paginated collection operation instead of API Platform's native `page` and `itemsPerPage`. 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 # Third page of 20 items GET /products?page[offset]=40 # Request 50 items per page (up to maximum of 100) GET /products?page[limit]=50 # 50 items per page, second page GET /products?page[limit]=50&page[offset]=50 ``` A `page[limit]` below `1` falls back to the default items per page, and a negative `page[offset]` is treated as `0`. A page number parameter such as `page=3` is not supported. ### 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 Providers extending `Spryker\ApiPlatform\State\Provider\AbstractProvider` call `buildPaginationTransfer()` to read `page[limit]` and `page[offset]` from the request into a `PaginationTransfer`, pass it to the facade, and call `setCollectionPagination()` with the total number of results: ```php $paginationTransfer = $this->buildPaginationTransfer(); $criteriaTransfer->setPagination($paginationTransfer); $collectionTransfer = $this->facade->getCollection($criteriaTransfer); $nbResults = $collectionTransfer->getPagination()?->getNbResults(); if ($nbResults !== null) { $this->setCollectionPagination($paginationTransfer->getOffsetOrFail(), $paginationTransfer->getLimitOrFail(), $nbResults); } return $resources; ``` `buildPaginationTransfer()` resolves `page[limit]` against `paginationItemsPerPage` and `paginationMaximumItemsPerPage` and `page[offset]` against `0`. `setCollectionPagination()` renders the top-level `meta.pagination` object with `numFound`, `currentPage`, `maxPage`, and `currentItemsPerPage`, and the `first`, `last`, `prev`, and `next` entries of the top-level `links` object. Collection members do not carry pagination data. ```json { "links": { "first": "https://glue-backend.mysprykershop.com/products?page[limit]=20&page[offset]=0", "last": "https://glue-backend.mysprykershop.com/products?page[limit]=20&page[offset]=80", "prev": "https://glue-backend.mysprykershop.com/products?page[limit]=20&page[offset]=20", "next": "https://glue-backend.mysprykershop.com/products?page[limit]=20&page[offset]=60" }, "meta": { "pagination": { "numFound": 97, "currentPage": 3, "maxPage": 5, "currentItemsPerPage": 20 } }, "data": [] } ``` Native API Platform resources that do not extend `AbstractProvider` return a `TraversablePaginator` instead. See [Native API Platform resources](/docs/integrations/spryker-api/api-platform/native-api-platform-resources.html). ### 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/integrations/spryker-api/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. `includes` is declared once on the parent resource — the child resource does not need a reverse declaration. ```yaml includes: - relationshipName: addresses targetResource: CustomersAddresses uriVariableMappings: customerReference: customerReference ``` **Entry fields:** | Field | Required | Description | |-------|----------|-------------| | `relationshipName` | Yes | Name used in the `?include=` parameter and as the JSON:API relationship key. | | `targetResource` | Yes | The `name` of the included resource as declared in its `resource.yml` (for example, `CustomersAddresses`). Also determines the JSON:API `type` field of the related resources. | | `uriVariableMappings` | Conditional | Maps properties from the parent resource to the URI variables of the included resource. Required when the included resource is routed by URI variables. Format: `parentProperty: childUriVariable`. Ignored when `resolverClass` is set. | | `uriTemplate` | Optional | Explicit URI template for the included resource when it has multiple operations and the relationship must target a specific path (for example, `/abstract-products/{abstractProductSku}/abstract-product-prices`). | | `resolverClass` | Optional | Fully qualified class name of a relationship resolver. Use when the relationship cannot be expressed via URI variables — the resolver receives the parent resources and the request context, and returns the related resources directly. When `resolverClass` is set, `uriVariableMappings` and `uriTemplate` are not used for routing. See [Custom relationship resolvers](/docs/integrations/spryker-api/api-platform/relationships.html#custom-relationship-resolvers). | | `autoInclude` | Optional | Resolve this relationship for every response of the parent type, even when the client did not request it via `?include=`. Use `autoIncludeMaxDepth` and `autoIncludeMinDepth` to bound where in the response graph the auto-include applies. | #### URI-variable mapping example For relationships routed by sub-resource URLs, map parent properties to child URI variables: ```yaml includes: - relationshipName: abstract-product-prices targetResource: AbstractProductPrices uriTemplate: /abstract-products/{abstractProductSku}/abstract-product-prices uriVariableMappings: sku: abstractProductSku ``` #### Resolver-based example For relationships whose targets cannot be derived from URI variables (for example, derived from order state or aggregated across multiple sources), reference a resolver class: ```yaml includes: - relationshipName: order-shipments targetResource: OrderShipments resolverClass: Spryker\Glue\ShipmentsRestApi\Api\Storefront\Relationship\OrderShipmentsRelationshipResolver ``` **Further reading:** [Resource relationships](/docs/integrations/spryker-api/api-platform/relationships.html) — full reference for declaring, resolving, and troubleshooting relationships between API Platform resources, including provider-based and resolver-based dispatch, response shape, validation, and worked examples. ## Sort priority for included resources The JSON:API response wraps related resources in an `included` array. By default, API Platform sorts that array alphabetically by resource `type`. Use `includedSortPriority` on a resource to override where its entries appear relative to other types. ### How it works | Rule | Behavior | |------|----------| | Default | Every resource has an implicit priority of `0`. | | Higher priority | Entries appear **later** in the `included` array. | | Equal priority | Entries are sorted alphabetically by `type`. | The priority is read from the resource's own `.resource.yml` and applied globally to every response that surfaces that type in `included`. ### Syntax ```yaml resource: name: CartItems shortName: items includedSortPriority: 100 ``` The generator passes the value through to the generated `#[ApiResource]` attribute via `extraProperties`: ```php #[ApiResource( shortName: 'items', extraProperties: ['includedSortPriority' => 100], // ... )] ``` ### When to set a custom priority Set `includedSortPriority` higher than `0` when a resource must appear after its nested children in the `included` array. The typical case is cart-item-like resources whose `?include=` chain resolves to abstract or concrete products: keeping the parent items last preserves the ordering of the legacy REST API and matches the order most clients expect when iterating the `included` array. The following resources ship with `includedSortPriority: 100`: - `items` - `guest-cart-items` - `bundle-items` - `configurable-bundle-template-image-sets` All other shipped resources rely on the default of `0`. Override the priority on project-level resources only when you need to enforce a specific ordering in `included`. {% info_block infoBox "Sort priority is not a guarantee of stable ordering across versions" %} `includedSortPriority` is a hint for the sort algorithm, not a JSON:API contract. Clients should still address resources by `type` and `id` rather than by index in the `included` array. {% endinfo_block %} ## 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. ### Extending an existing resource (schema layering) 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 [Integrate API Platform security](/docs/integrations/spryker-api/authenticating-and-authorization/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/integrations/spryker-api/authenticating-and-authorization/security.html). For instructions on setting up scopes, see [Integrate the authorization scopes](/docs/integrations/spryker-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/integrations/spryker-api/authenticating-and-authorization/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 # PascalCase plural — used for schema merging shortName: customers # lowercase kebab-case plural — JSON:API type + URL segment # ✅ Good — multi-word resource: name: AbstractProductPrices shortName: abstract-product-prices # ❌ Bad — wrong shortName casing/form resource: name: Customers shortName: Customer # Should be lowercase plural # ❌ Bad — abbreviated, unclear 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 ```

API Platform

Fri, 11 Sep 2026 08:04:21 +0000

Spryker’s API Platform integration provides schema-based API resource generation with automatic OpenAPI documentation. This allows you to define your API resources using YAML schemas and automatically generate fully functional API endpoints with validation, pagination, and serialization.

This document describes the API Platform architecture and how it integrates with Spryker.

What is API Platform

API Platform is a framework for building modern APIs based on web standards and best practices. In Spryker, it complements the existing Glue API infrastructure by providing:

Schema-based resource generation: Define resources in YAML, generate PHP classes automatically
Automatic OpenAPI documentation: Interactive API documentation generated from schemas
Built-in validation: Symfony Validator integration with operation-specific rules
Pagination support: Standardized pagination with configurable defaults
State management: Separate providers (read) and processors (write) for clean architecture

Read more about the API Platform project at api-platform.com.

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

Architecture overview

Resource generation workflow

>Schema Files (YAML)
    ↓
Schema Discovery & Validation
    ↓
Multi-layer Schema Merging (Core → Feature → Project → [Code Buckets])
    ↓
Resource Class Generation
    ↓
API Platform Resource (with attributes)
    ↓
API Endpoints

Core components

1. Schema files

Resources are defined in YAML files located in module directories:

>src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resource.yml
src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml

Example resource schema src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resource.yml:

resource:
  name: Customers
  shortName: customers
  description: "Customer resource for backend API"

  provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider"
  processor: "Pyz\\Glue\\Customer\\Api\\Backend\\Processor\\CustomerBackendProcessor"

  paginationEnabled: true

  operations:
    - type: Post
    - type: Get
    - type: GetCollection
    - type: Patch
    - type: Delete

  properties:
    email:
      type: string
      description: "Customer email address"
    customerReference:
      type: string
      identifier: true
      writable: false

Example validation schema src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml:

post:
  name:
    - NotBlank:
        message: First name is required
    - Length:
        min: 2
        max: 64
        minMessage: First name must be at least 2 characters
        maxMessage: First name cannot exceed 64 characters

patch:
  name:
    - Optional:
        constraints:
          - Length:
              min: 2
              max: 64
              minMessage: First name must be at least 2 characters
              maxMessage: First name cannot exceed 64 characters

2. Generated resources

The generator creates PHP classes with API Platform attributes:

src/Generated/Api/Backend/CustomersBackendResource.php

<?php

namespace Generated\Api\Backend;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiProperty;
use Symfony\Component\Validator\Constraints as Assert;

#[ApiResource(
    operations: [new Post(), new Get(), new GetCollection(), new Patch(), new Delete()],
    shortName: 'customers',
    provider: CustomerBackendProvider::class,
    processor: CustomerBackendProcessor::class
)]
final class CustomersBackendResource
{
    #[ApiProperty(identifier: true, writable: false)]
    public ?string $customerReference = null;

    #[ApiProperty]
    #[Assert\NotBlank(groups: ['customers:create'])]
    #[Assert\Email(groups: ['customers:create'])]
    public ?string $email = null;

    // Getters, setters, toArray(), fromArray()...
}

3. State providers and processors

Detailed information about the API-Platform Provider and Resources can be found on the public docs:

Provider (read operations):

class CustomerBackendProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        // Fetch and return data from your business layer
        return $customerResource;
    }
}

Processor (write operations):

class CustomerBackendProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
    {
        // Persist changes through your business layer
        return $updatedResource;
    }
}

API types

Any of the existing APIs can be extended using API Platform.

Spryker supports multiple API types for different use cases:

Glue API

This API is configured to serve the JSON:API format by default; to change the supported formats, see Configure supported formats. Projects migrating their APIs can provide new APIs as well as supporting the existing ones while migrating.

API Type: storefront
Application: Glue
Base URL: http://glue.eu.spryker.local/ - Configurable per project
Use cases: Customer-facing APIs, mobile apps, PWAs

GlueStorefront API

This API serves the JSON:API format by default; additional formats, such as JSON-LD, can be enabled per project. For instructions, see Configure supported formats.

API Type: storefront
Application: GlueStorefront
Base URL: http://glue-storefront.eu.spryker.local/ - Configurable per project
Use cases: Customer-facing APIs, mobile apps, PWAs

GlueBackend API

API Type: backend
Application: GlueBackend
Base URL: http://glue-backend.eu.spryker.local/
Use cases: Admin panels, internal tools, ERP integrations

Merchant Portal API

API Type: merchant-portal
Application: MerchantPortal
Base URL: http://mp.glue.eu.spryker.local/
Use cases: Marketplace merchant interfaces
Example: /products

Multi-layer schema merging

One of the key features is support for multi-layer schema definitions that automatically merge:

Core layer (vendor/spryker):

resource:
  name: Customers
  properties:
    email:
      type: string

Feature layer (src/SprykerFeature):

resource:
  name: Customers
  properties:
    loyaltyPoints:
      type: integer

Project layer (src/Pyz):

resource:
  name: Customers
  properties:
    email:
      required: true  # Override core
    customField:
      type: string    # Project-specific

Result: A single merged resource with all properties, project code-bucket layer taking precedence.

Integration with Spryker architecture

Dependency Injection

API Platform fully integrates with Symfony Dependency Injection:

// config/Zed/ApplicationServices.php
$services->load('Pyz\\Zed\\', '../../../src/Pyz/Zed/');

Providers and Processors are automatically discovered and can use constructor injection:

class CustomerBackendProvider implements ProviderInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
        private CustomerRepositoryInterface $customerRepository,
    ) {}
}

Facade integration

Resources can leverage existing Spryker facades:

class CustomerBackendProcessor implements ProcessorInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
    ) {}

    public function process(mixed $data, Operation $operation, ...): mixed
    {
        $customerTransfer = $this->mapToTransfer($data);
        $response = $this->customerFacade->createCustomer($customerTransfer);
        return $this->mapToResource($response->getCustomerTransfer());
    }
}

Resource generation

Console commands

All the following commands can be used with a specific GLUE_APPLICATION by prefixing them with GLUE_APPLICATION=GLUE_BACKEND environment variable. For example: docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug --list

# Generate resource classes for all configured API types at once. Usually used during deployment/installation.
docker/sdk cli glue api:generate

# Generate API type specific resource classes. Usually used during development.
docker/sdk cli glue api:generate backend

# Validate schemas only to see if there is any issue in the definitions
docker/sdk cli glue api:generate --validate-only

Debug commands

# List all resources to see which ones are defined in the schema files.
docker/sdk cli glue  api:debug --list

# Inspect specific resource and print details about properties and operations
docker/sdk cli glue  api:debug customers --api-type=backend

# Show merged schema
docker/sdk cli glue  api:debug customers --api-type=backend --show-merged

# Show contributing files for a resource
docker/sdk cli glue  api:debug customers --api-type=backend --show-sources

Features

Automatic OpenAPI documentation

API Platform generates interactive OpenAPI documentation:

Swagger UI at the root URL / for example http://glue-backend.eu.spryker.local/
Query parameters declared under an operation’s openapiContext.parameters, such as sort or filter[...], are rendered as input fields. Paginated collections get page[limit] and page[offset] automatically.
Operations marked with openapi: false keep their route but are not listed. See Operation options.

You can disable this interface in production environments by configuring the settings in your api_platform.php configuration file. For details, see Enable the documentation UI only in development.

Built-in validation

Validation rules from *.validation.yml files are converted to Symfony Validator constraints:

post:
  email:
    - NotBlank
    - Email

Becomes:

#[Assert\NotBlank(groups: ['customers:create'])]
#[Assert\Email(groups: ['customers:create'])]
public ?string $email = null;

Pagination support

Standardized JSON:API offset pagination with query parameters:

>GET /customers?page[limit]=20&page[offset]=20

Providers extending AbstractProvider call buildPaginationTransfer() to read page[limit] and page[offset] from the request into a PaginationTransfer, pass it to the facade, and call setCollectionPagination() with the total number of results. The response carries the summary in the top-level meta.pagination object and the first, last, prev, and next links in the top-level links object. See Resource schemas — Pagination.

Operation-specific behavior

Define different validation and behavior per operation:

operations:
  - type: Post            # Create
  - type: Get             # Read one
  - type: GetCollection   # Read many
  - type: Patch           # Update
  - type: Delete          # Delete

Each operation can have specific validation rules and security settings.

Relationships

Include related resources via the ?include= query parameter:

includes:
  - relationshipName: addresses
    targetResource: CustomersAddresses
    uriVariableMappings:
      customerReference: customerReference

Request:

GET /customers/customer--35?include=addresses

Response includes both the customer and related addresses in JSON:API format. No provider code changes required - relationships work automatically through decoration.

For detailed information, see Resource relationships.

Sparse fieldsets

Request only the attributes you need using the fields query parameter:

GET /stores?fields[stores]=name,locale

This returns only name and locale in the response attributes, reducing payload size. Sparse fieldsets work with relationships too — filter attributes on both the main resource and included resources.

For detailed information, see Sparse Fieldsets.

Performance

Opcache

API Platform loads a significantly larger class graph per request than the legacy Glue stack—the Symfony kernel, serializer, validator, security components, and the generated resource classes. Opcache must be enabled on all deployed environments; without it, every request recompiles this class graph, adding a flat overhead of seconds per request. For configuration details, see Opcache activation.

Cache warming

API Platform deployment requires two sequential steps, not alternatives:

Generate the API resource classes from the schema files:

docker/sdk cli glue api:generate

Warm the application cache—including the router cache—once the resources from step 1 exist. Run it per Glue application:

docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue cache:warmup
docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue cache:warmup

API Platform registers its operations as routes in the standard Symfony router, whose compiled matcher and generator are dumped to data/cache/Glue<Storefront|Backend>/<environment>/url_matching_routes.php and url_generating_routes.php. cache:warmup builds these dumps from the resource collection produced in step 1. Add both steps to your deployment and installation recipes for every API Platform application.

Use cache:warmup, not api:router:cache:warm-up

api:router:cache:warm-up warms only the legacy Glue (GlueApplication) custom-route router—it does not build the API Platform router dump. Use cache:warmup (or cache:clear) to warm the API Platform router.

Multi-container and cloud deployments

In production, applications run with debug disabled. The router dump is then written once and never revalidated—whatever route set it was first built from is frozen for the life of the container.

In a single-container setup this is harmless: the cache is warmed in the same place that serves requests, with the full route set. In a multi-container topology where resource generation runs in a build container and requests are served by a separate runtime container (for example, AWS ECS), you must guarantee the router dump is built against the complete resource collection for the runtime container—either warmed in the runtime container after deployment, or baked at build time only if data/cache is shipped to every runtime replica with the full route set.

If the dump is built before resources are generated (an empty or incomplete collection), the runtime container freezes that empty dump and:

every API request returns HTTP 404 (Glue code 007, legacy fallthrough) because the route is absent from the matcher;
once the matcher is partially rebuilt, data endpoints return HTTP 500 from IRI generation (RouteNotFoundException), because the URL generator dump is also empty;
/docs.json returns 0 paths, even though api:debug --list shows the resources resolving correctly.

To recover a frozen container, clear and re-warm the cache (cache:clear) with the full resource collection present.

Property-level access control

properties:
  password:
    writable: true   # Can be written
    readable: false  # Not in responses

Comparison with Glue API

Feature	API Platform	Glue API
Definition	Schema-based (YAML)	Code-based (PHP)
Documentation	Auto-generated OpenAPI	Manual
Validation	Declarative	Programmatic
Standards	JSON:API by default; JSON-LD and other formats available	JSON API
Use cases	Standard CRUD	Complex business logic

Both can coexist in the same application. For further migration guidance, see Migrate to API Platform.

Install the Products Backend API

Thu, 10 Sep 2026 15:49:24 +0000

This document describes how to install the [Products Backend API](/docs/pbc/all/product-experience-management/latest/products-backend-api.html), which exposes concrete and abstract product data at `/products` on the Glue Backend API. ## 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) | | Self-Service Portal | {{page.release_tag}} | [Install Self-Service Portal](/docs/pbc/all/self-service-portal/latest/install/install-self-service-portal.html) | The Self-Service Portal feature is optional. Install it only to use the `productClass` and `shipmentType` attributes. Step 1 installs the remaining modules the API depends on, so you do not have to install them beforehand. The API resource is generated by API Platform. If your project does not use API Platform yet, follow [Integrate API Platform](/docs/integrations/spryker-api/migrate-from-glue-to-api-platform/integrate-api-platform.html) before you continue. ## Install feature core ### 1) Install the required modules Install the feature and API Platform using Composer: ```bash composer require spryker-feature/product-experience-management:"{{page.release_tag}}" spryker/api-platform:"^1.0.0" --update-with-dependencies ``` {% info_block warningBox "spryker/api-platform" %} The Product Experience Management feature declares `spryker/api-platform` as a suggested dependency, not a required one. Install it explicitly, as shown above. Without it, the `/products` resource is never registered and the endpoint returns `404`. {% endinfo_block %} The API registers plugins that ship in modules the feature does not constrain to the versions providing them. Update those modules explicitly: ```bash composer require \ spryker/category:"^5.25.0" \ spryker/price-product:"^4.54.0" \ spryker/product:"^6.57.0" \ spryker/product-attribute:"^1.22.0" \ spryker/product-bundle:"^7.29.0" \ spryker/product-category:"^4.34.0" \ spryker/product-extension:"^1.6.0" \ spryker/product-image:"^3.22.0" \ spryker/shipment-type:"^1.3.0" \ spryker/stock:"^8.17.0" \ spryker/tax:"^5.20.0" \ spryker/tax-product-connector:"^4.13.0" \ spryker/uuid-behavior:"^1.3.0" \ --update-with-dependencies ```

What each version provides

| MODULE | MINIMUM VERSION | PROVIDES | | --- | --- | --- | | spryker/product | ^6.57.0 | Collection writers and the plugin stacks registered in step 4 | | spryker/product-extension | ^1.6.0 | Interfaces of the collection validator plugins | | spryker/category | ^5.25.0 | `CategoryExistsProductAbstractCollection*ValidatorPlugin`, `spy_category.uuid` | | spryker/tax | ^5.20.0 | `spy_tax_set.uuid` | | spryker/tax-product-connector | ^4.13.0 | `TaxSetExistsProductAbstractCollection*ValidatorPlugin` | | spryker/price-product | ^4.54.0 | Price collection validator plugins, `spy_price_product_store.uuid` | | spryker/product-image | ^3.22.0 | Image set expander and validator plugins, `spy_product_image_set.uuid` | | spryker/product-category | ^4.34.0 | `ProductCategoryAbstractCollectionExpanderPlugin` | | spryker/product-attribute | ^1.22.0 | `SuperAttributeProductConcreteExpanderPlugin` | | spryker/product-bundle | ^7.29.0 | `ProductBundleProductConcreteCollection*ValidatorPlugin` | | spryker/shipment-type | ^1.3.0 | `ShipmentTypeExistsProductConcreteCollection*ValidatorPlugin` | | spryker/stock | ^8.17.0 | `StockProductConcreteCollectionAfterUpdatePlugin`, stock validator plugins | | spryker/uuid-behavior | ^1.3.0 | UUID behavior used by the new schema definitions |

To use the `productClass` and `shipmentType` attributes, install the Self-Service Portal feature as well: ```bash composer require spryker-feature/self-service-portal:"{{page.release_tag}}" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | | --- | --- | | ProductExperienceManagement | vendor/spryker-feature/product-experience-management | | ApiPlatform | vendor/spryker/api-platform | Make sure the installed module versions are at least the ones listed above. If a validator plugin class cannot be found in step 4, the corresponding module is below its minimum version. {% endinfo_block %} ### 2) Set up configuration The API references categories, tax sets, prices, and image sets by UUID. Enable the UUID columns for those entities. **src/Pyz/Zed/Category/CategoryConfig.php** ```php */ protected function getProductConcreteExpanderPlugins(): array { return [ // Keep the plugins your project already registers. new SuperAttributeProductConcreteExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductAbstractCollectionExpanderPluginInterface> */ protected function getProductAbstractCollectionExpanderPlugins(): array { return [ new TaxSetProductAbstractCollectionExpanderPlugin(), new ProductImageAbstractCollectionExpanderPlugin(), new ProductCategoryAbstractCollectionExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\Product\Dependency\Plugin\ProductConcretePluginUpdateInterface> */ protected function getProductConcreteAfterUpdateCollectionPlugins(): array { return [ new ImageSetProductConcreteAfterUpdatePlugin(), new PriceProductConcreteAfterUpdatePlugin(), new StockProductConcreteCollectionAfterUpdatePlugin(), new ProductSearchProductConcreteAfterUpdatePlugin(), new ProductValidityUpdatePlugin(), new ProductClassProductConcreteAfterUpdatePlugin(), new ShipmentTypeProductConcretePostUpdatePlugin(), new ProductBundleProductConcreteAfterUpdatePlugin(), new ProductBundleDeactivatorProductConcreteAfterUpdatePlugin(), ]; } /** * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductConcreteCollectionCreateValidatorPluginInterface> */ protected function getProductConcreteCollectionCreateValidatorPlugins(): array { return [ new PriceProductConcreteCollectionCreateValidatorPlugin(), new ProductImageSetExistsProductConcreteCollectionCreateValidatorPlugin(), new StockExistsProductConcreteCollectionCreateValidatorPlugin(), new ShipmentTypeExistsProductConcreteCollectionCreateValidatorPlugin(), new ProductClassExistsProductConcreteCollectionCreateValidatorPlugin(), new ProductBundleProductConcreteCollectionCreateValidatorPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductConcreteCollectionUpdateValidatorPluginInterface> */ protected function getProductConcreteCollectionUpdateValidatorPlugins(): array { return [ new PriceProductConcreteCollectionUpdateValidatorPlugin(), new ProductImageSetExistsProductConcreteCollectionUpdateValidatorPlugin(), new StockExistsProductConcreteCollectionUpdateValidatorPlugin(), new ShipmentTypeExistsProductConcreteCollectionUpdateValidatorPlugin(), new ProductClassExistsProductConcreteCollectionUpdateValidatorPlugin(), new ProductBundleProductConcreteCollectionUpdateValidatorPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductAbstractCollectionCreateValidatorPluginInterface> */ protected function getProductAbstractCollectionCreateValidatorPlugins(): array { return [ new CategoryExistsProductAbstractCollectionCreateValidatorPlugin(), new TaxSetExistsProductAbstractCollectionCreateValidatorPlugin(), new PriceProductAbstractCollectionCreateValidatorPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductAbstractCollectionUpdateValidatorPluginInterface> */ protected function getProductAbstractCollectionUpdateValidatorPlugins(): array { return [ new CategoryExistsProductAbstractCollectionUpdateValidatorPlugin(), new TaxSetExistsProductAbstractCollectionUpdateValidatorPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} If a validator plugin is missing, the API accepts references to entities that do not exist and the write fails later with a database error instead of a `422` validation error. If an expander plugin is missing, the corresponding data is absent from read responses. {% endinfo_block %} ### 5) Generate the API resources Clear the Glue Backend cache and regenerate the API resources: ```bash rm -rf data/cache/GlueBackend/ docker/sdk cli "GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue api:generate" docker/sdk cli "GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue cache:clear" ``` Replace `` with your environment name, for example, `development`. ## Verification Request a Back Office access token as described in [Authenticate as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html), then retrieve a product collection: ```bash curl "https://glue-backend.mysprykershop.com/products?page[limit]=1" \ -H "Authorization: Bearer {access_token}" ``` The integration is successful when the request returns `200` with a `data` array. A `404` means the resource was not generated — repeat step 5 and confirm that `spryker/api-platform` is installed. A `401` means the access token is missing or expired.