Catalog Promotions
The Catalog Promotions system in Sylius offers a powerful way to apply promotions across multiple products at once. If you're familiar with Cart Promotions, Catalog Promotions will feel familiar, but they apply directly to products in your catalog, rather than at checkout.
Catalog Promotions are managed through a combination of scopes and actions:
Scopes define which products (e.g., by taxon or specific product variants) the promotion applies to.
Actions determine what happens when the promotion is applied, such as a percentage discount.
You can also:
Set start and end dates for Catalog Promotions.
Assign priority (with higher-priority promotions applied first).
Set a promotion as exclusive, ensuring only one promotion is applied when multiple promotions could apply.
Additionally, promotions can be assigned to specific channels.
Applying promotions to a large catalog may take some time to process. Expect a delay of 2-10 minutes starting from the specified activation time, depending on the size of your catalog.
Catalog Promotion Parameters
A Catalog Promotion has a few key parameters, including a unique code and a name:
The code should contain only letters, numbers, dashes, and underscores (like all Sylius codes). Using snake_case for codes is recommended.
Channels
You can specify which channels the promotion applies to:
Scopes
Scopes define the range of products affected by the promotion. For example, you can apply a promotion to specific product variants:
Variant codes are used instead of IRIs because this is a configuration, not a relationship to another resource.
for_products
['products' => [$productCode]]
for_taxons
['taxons' => [$taxonCode]]
for_variants
['variants' => [$variantCode]]
Actions
Actions define the behavior of the promotion, such as applying a percentage discount:
fixed_discount
[$channelCode => ['amount' => $amountInteger]]
percentage_discount
['amount' => $amountFloat]
Translations
You can also add translations to provide labels and descriptions for different languages:
How to create a Catalog Promotion?
To create a catalog promotion, you can either use the API or do it programmatically.
API Creation
First, authorize yourself as an admin (guests cannot create promotions), then call the POST
endpoint to create a basic catalog promotion:
If successful, you will receive a 201
status code, indicating that the promotion has been created with only a name and code.
Programmatically
You can also create a catalog promotion using Sylius' factory service:
However, both API and programmatically created promotions are not useful without additional configurations such as scopes and actions.
Adding a Scope and Action to a Catalog Promotion
To make a Catalog Promotion functional, you need to add scopes and actions.
API Extension
Extend the previous POST
request to include scope, action, and translation configurations:
This will create a Catalog Promotion with:
Scope: targeting specific product variants.
Action: applying a 50% discount.
Translation: localized label and description.
Programmatically
Here’s how to configure a Catalog Promotion programmatically:
When creating a promotion programmatically, remember to dispatch the CatalogPromotionCreated
event to ensure it is applied to your catalog.
Asynchronous vs. Synchronous Processing of Catalog Promotions
Catalog Promotions are processed asynchronously by default, meaning changes may take some time to reflect in the product catalog. This delay depends on the size of the catalog.
To enable asynchronous processing, run the following command to start the messenger consumer:
Synchronous Processing
If you prefer synchronous processing (immediate application of promotions), you can override the configuration by setting up the config/packages/messenger.yaml
file:
Synchronous processing is only recommended for small catalogs, as it may degrade user experience with larger data sets.
How Catalog Promotions Are Applied
When a new promotion is created or updated, the system triggers API Platform events (for API) and Resource events (for UI). These events dispatch the CatalogPromotionCreated
or CatalogPromotionUpdated
events to the event bus.
The CatalogPromotionUpdateListener listens for these events and recalculates the product catalog using the updated promotion data. Recalculation across the entire product catalog is handled by the BatchedApplyCatalogPromotionsOnVariantsCommandDispatcher
, which applies the promotions to all relevant product variants.
To manually reapply a catalog promotion, refer to the "Adding a Scope and Action to a Catalog Promotion" section.
Removal of Catalog Promotions
Removing a Catalog Promotion involves:
Turning off the promotion.
Recalculating the product catalog.
Deleting the promotion resource.
When using asynchronous mode, you'll need to start the worker for two transports:
The main transport handles recalculating the catalog.
The catalog_promotion_removal transport handles the removal of the promotion.
Here’s the command to start both processes:
Each transport has its own failure transport, which stores any unprocessed messages. These transports are:
main_failed for the main transport.
catalog_promotion_removal_failed for the catalog promotion removal transport.
You can read more about handling failures in the Symfony Messenger documentation.
For synchronous processing, no additional configuration is required.
Managing Catalog Promotion Priority
Catalog promotions in Sylius must have unique priorities to ensure the correct application order. Here’s how priority is handled in different scenarios:
Creating a New Catalog Promotion
Higher priority: Adding a promotion with a priority higher than all existing promotions does not affect the others.
Lower priority: Adding a promotion with a lower priority increases the priority of all existing promotions by 1.
Equal priority: Adding a promotion with the same priority as an existing one increases the priority of all promotions with equal or higher priority by 1.
Priority of -1: A priority of -1 assigns the new promotion a priority one greater than the current highest value.
Negative priorities (< -1): These start from the lowest existing priority, counting backward. If a calculated priority is already taken, all equal or higher priorities are increased by 1.
Updating an Existing Catalog Promotion
Updating a promotion’s priority to match another promotion decreases the matching promotion’s priority by 1.
Last updated