Basket Synchronization

Retailer apps must keep the host cart and the Mealz basket aligned using BasketSynchronizationManager.

Basket transfer (affiliated No Supplier → your app) also lands products through this synchronizer, but the handoff itself is a deep link into My Meals — see Basket Transfer. Do not confuse it with redirectToCart (open your in-app cart while the shopper is already in Mealz UI).

Register a Synchronizer

Register after SdkConfiguration.shared.start and before any Mealz screen. If you never register, Mealz → cart updates are silently ignored (updateBasket is not called).

Implement RetailerBasketSynchronizer so Mealz can push product quantity changes into your cart:

BasketSynchronizationManager.shared.registerRetailerBasketSynchronizer(
    synchronizer: /* RetailerBasketSynchronizer */
)

RetailerProduct

Field	Type	Meaning
id	String	Retailer product / SKU id.
quantity	Int	See Two directions below — meaning differs by API.

Two directions

Basket sync uses two different contracts:

Direction	API	Quantity meaning
Mealz → host	RetailerBasketSynchronizer.updateBasket	Signed deltas: positive = add, negative = remove. Apply the change; do not treat the value as the final cart quantity.
Host → Mealz	notifyRetailerBasketChanged	Absolute quantities for Mealz-related lines currently in the host cart (non-Mealz SKUs omitted).

Deltas, not full quantities

updateBasket receives signed deltas (quantity changes to apply), aligned with Mealz SSR basket sync.

In older MealzCore / MealzAndroid / MealziOSSDK libraries, callbacks often exposed the final expected quantities. That model caused desyncs when several actions ran in parallel. MealzUIKit matches the SSR delta model so concurrent add/remove operations stay consistent — treat each RetailerProduct.quantity as a change to apply, not as an absolute stock level in the cart.

After Mealz pushes deltas, apply them to your cart and call notifyRetailerBasketChanged promptly. Mealz keeps pending updates for about 10 seconds while waiting for the host to echo the new absolute basket; slow confirmation can cause races with the next WebView basket state.

Notify Mealz When the Retailer Cart Changes

Whenever the user (or your app) changes the retailer cart outside Mealz, push the absolute Mealz-related product list:

BasketSynchronizationManager.shared.notifyRetailerBasketChanged(
    productLists: [
        RetailerProduct(id: "sku-1", quantity: 2),
        RetailerProduct(id: "sku-2", quantity: 1),
    ]
)

Checkout / Payment

When the user starts checkout on the retailer side:

BasketSynchronizationManager.shared.paymentStarted(
    totalPrice: 42.50,
    productList: currentRetailerProducts,
    orderId: nil // optional
)

paymentStarted is best-effort: network / API failures are swallowed so the retailer app does not crash. Ensure retailer mode and an external store are set beforehand; do not rely on exceptions for control flow.

When payment succeeds:

BasketSynchronizationManager.shared.handlePayment(
    totalPrice: 42.50,
    productList: paidProducts,
    orderId: "order-123"
) {
    // Optional: clear retailer cart, navigate away, etc.
}

warning

paymentStarted and handlePayment are retailer mode only and require a store set via setSelectedStoreWithExternalId.