Cart Discount Coordination Engine

The problem

Three independent systems — the Shopify platform, the Rebuy Smart Cart, and manual customer input — apply discounts in isolation. When they don't reconcile cleanly, a customer sees one price in the cart and a different one at checkout, and loses trust.

The result was recurring weekly support tickets, cart abandonment, and eroded customer confidence.

The solution

A coordination layer built around Rebuy events and Shopify cart state: detect the active discount mode, reconcile the authoritative line-level impact, and render truthful prices in real time. Cart totals now match checkout in the critical scenarios the system handles — including stacked URL and automatic promotions.

Key technical decisions

State signature tracking. Rather than reprocessing on every cart change, the system tracks a signature of the current discount plus cart-line identities. If nothing has changed, recalculation is skipped — preventing DOM thrashing on high-traffic carts while still responding correctly when duplicate variant lines change independently.

Proportional allocation with rounding reconciliation. Distributing a percentage discount across mixed-price items with naive rounding produces €0.01 discrepancies. A two-pass algorithm allocates proportionally, then reconciles the remainder so line items always sum to the expected subtotal.

Mode-aware handling. Discount sources behave differently, and the system treats them differently rather than forcing everything through one path:

• Automatic Buy-X-Get-Y, URL-driven multiples, and automatic free-item scenarios are deferred to Shopify's own checkout-level logic or to the multiples handler, because the platform already renders them correctly.
• Manual Rebuy codes and regular checkout-level discounts run the custom pricing path, reconciling the line-item display to the already-rendered subtotal so the preview stays aligned with what checkout will charge.

The point is a deliberate split: defer where the platform is authoritative, run custom preview logic where it isn't, and keep the two consistent.

Multi-mode combination handling. When a multiples code (3-for-2, 4-for-3) combines with a percentage discount, the system identifies which items are free versus paid, keeps Shopify's split free line at €0.00, allocates the order-level discount across paid lines only, and presents both discount types clearly.

Key-first line matching. A product or variant ID is not always a unique cart row: the same variant can appear more than once with different properties or selling plans. The renderer therefore matches a cart line by its Shopify cart key first, with a compatibility fallback where needed. That keeps snapshots, DOM updates, and discount allocations attached to the right row.

Bounded resilience, not endless polling. Rebuy and Shopify can expose cart data, discount messages, and Smart Cart DOM at different moments. The coordinator uses short, capped retries, resets them on cart lifecycle events, and rechecks restored or newly visible pages. This protects delayed connections and in-app browsers without changing Shopify's discount calculation.

Recent cart UX hardening

• URL discounts use Rebuy's native summary. Instead of injecting a separate notice above the Smart Cart footer, the URL discount manager locks Rebuy's own heading closed, changes it to RABATTCODE ANGEWENDET!, and keeps the applied tag and amount visible.
• Conflicting entry is prevented without hiding context. The code-input disclosure and arrow are disabled while a URL code is active, but customers can still remove the visible applied tag. On removal, the manager clears the URL-code cookie and restores Rebuy's normal input control.
• Ownership remains explicit. URL 3-for-2 and 4-for-3 codes remain with the dedicated multiples handler, rather than competing with the URL discount manager.

Architecture (high level)

The module names below are the actual modules in the codebase.

• RebuyEventManager — the event hub. Normalizes rebuy:* events, holds and refreshes current cart state, and republishes normalized cart:* and discount:* events that the rest of the system subscribes to.
• RebuyUtils — the shared utility layer. Owns cart reads and Ajax cart mutations, discount-source resolution (getActiveDiscount() resolves by precedence: manual Rebuy → checkout-level → automatic Buy-X-Get-Y → none), and the proportional allocation math. It also provides key-first cart-line identity and detects Shopify's automatic free lines.
• RebuyCartCallbacks — the renderer. Owns price DOM snapshotting, sale/compare-at rendering, proportional discount display, revert behavior when discount state changes, subtotal reconciliation, and the bounded recovery path for delayed URL discount rendering.
• FreeGiftHandler — manages code-based free gifts, kept separate from Rebuy's own gifts by a _free_gift_source line-item marker, and enforces gift quantity.
• MultiplesPromoHandler — manages 3-for-2 / 4-for-3 patterns and their combination with percentage and fixed discounts, including late-arriving cart UI and discount messages.
• URLDiscountManager — detects cookie-backed URL codes, coordinates their native Rebuy summary state, preserves the applied tag, and restores normal code entry when that tag is removed.
• Cart drawer initialisation — waits for the Rebuy runtime with capped initial and post-load retries, then falls back to event and readiness recovery so each module starts once.
• Adjacent modules: bundle-builder UI updates and storefront-specific configuration.

Coordination is centralized through RebuyEventManager (event flow) and RebuyUtils (shared discount/cart utilities), while each handler stays modular.

Technical challenges

Mathematical precision. Proportional allocation across mixed-price items while keeping the subtotal exact — solved with the two-pass reconciliation above. In e-commerce, cent-level accuracy is the foundation of trust, not a nicety.

Cross-source reconciliation. Automatic and URL-driven discounts rely on Shopify cart/checkout state; manual input originates in the Rebuy Smart Cart UI. That gap is exactly where "one price in cart, another at checkout" bugs live. The coordinator detects which source is active and applies the correct strategy per mode.

Debugging at scale. Module-level debug toggles — cart callbacks, free gifts, multiples, URL input, bundle updates, automatic discount handling — make event flow and state transitions traceable in production across 6 storefront configurations, which was essential for diagnosing timing and mode-conflict issues.

Cart-row identity and delayed rendering. The difficult failures were not only mathematical: a Smart Cart redraw can arrive after the cart state, and two visually similar lines can be different Shopify rows. Key-first matching plus capped lifecycle-aware retries keeps each display update attached to the correct row without turning the cart into a polling loop.

Impact

• Customer trust: eliminated "price changed at checkout" support tickets — a recurring weekly issue reduced to zero over 12+ months in production.
• Scale and stability: deployed across 6 international storefronts with multi-currency formatting, handling thousands of daily customer interactions with zero critical incidents.
• Performance: sub-100ms cart update latency via signature-based change detection.
• Complexity handled: layered discount states — multiples (3-for-2, 4-for-3), free gifts, manual codes, URL codes, and automatic discounts — presented clearly.
• Business enablement: made complex promotional campaigns with multiple simultaneous discounts possible without customer confusion.

What I learned

Work with platform constraints, not against them. The turning point was recognizing that some discount types are authoritative at checkout level. Rather than forcing everything through custom logic, the system defers where the platform is correct and provides accurate previews only where gaps exist.

Incremental refactoring beats big-bang rewrites. The system evolved through phased, incremental improvements — signature-based change detection, then allocation precision, then mode-aware handling and resilience improvements — deployed continuously across all storefronts without customer-facing disruption. Each phase added one capability and built confidence before the next.

Debug visibility is critical at scale. Module-level toggles saved hours when edge cases surfaced across different storefronts. Being able to trace event flow and state transitions in a live environment was invaluable for diagnosing timing issues, discount-mode conflicts, and late Smart Cart redraws.

Mathematical precision matters in production. Early versions had €0.01 rounding errors when allocating discounts across items. Small as they were, they eroded trust. Two-pass allocation eliminated them.

Future improvements

• Abstract the platform-specific integration points for broader applicability.
• Define standardized interfaces for different cart systems.
• Introduce adapter patterns for cross-platform use.

Client code is private; the technical docs above cover architecture and decisions in full.