From 860e3a118066bcee43be0ac809466a40c864a130 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Kali=C5=84ski?= <tomasz.kalinski@bitbag.pl>
Date: Mon, 15 Jun 2026 11:19:01 +0200
Subject: [PATCH] Document post-flush cart events in upgrade guide

---
 UPGRADE-2.3.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/UPGRADE-2.3.md b/UPGRADE-2.3.md
index 065ab29bd2..08813c3a2e 100644
--- a/UPGRADE-2.3.md
+++ b/UPGRADE-2.3.md
@@ -139,6 +139,38 @@
    | `ShippingBundle\...\ShippingMethodCalculatorExists` | `invalidShippingCalculator` | `invalidShippingCalculatorMessage` |
    | `ShippingBundle\...\ShippingMethodRule` | `invalidType` | `invalidTypeMessage` |
 
+## New Features
+
+1. New post-flush cart events have been added to `Sylius\Component\Order\SyliusCartEvents`.
+
+   The following events are now dispatched **after** `$manager->flush()`, allowing listeners to react once the cart has been safely persisted to the database:
+
+   | New constant | Event name |
+   |---|---|
+   | `SyliusCartEvents::CART_ITEM_POST_ADD` | `sylius.cart_item_post_add` |
+   | `SyliusCartEvents::CART_ITEM_POST_REMOVE` | `sylius.cart_item_post_remove` |
+   | `SyliusCartEvents::CART_POST_CHANGE` | `sylius.cart_post_change` |
+   | `SyliusCartEvents::CART_POST_CLEAR` | `sylius.cart_post_clear` |
+
+   Example usage — sending a cart to an external service only after it is stored:
+
+   ```php
+   use Sylius\Component\Order\SyliusCartEvents;
+   use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
+   use Symfony\Component\EventDispatcher\GenericEvent;
+
+   #[AsEventListener(event: SyliusCartEvents::CART_ITEM_POST_ADD)]
+   final class SendCartToMarketingAutomationListener
+   {
+       public function __invoke(GenericEvent $event): void
+       {
+           // Cart is already persisted — safe to send to external service.
+       }
+   }
+   ```
+
+   The existing pre-flush events (`CART_ITEM_ADD`, `CART_ITEM_REMOVE`, `CART_CHANGE`, `CART_CLEAR`) remain unchanged.
+
 ## Deprecations
 
 1. Passing a `Sylius\Component\Core\Calculator\ProductVariantPricesCalculatorInterface` directly to the following catalog-facing classes is deprecated since Sylius 2.3.