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, calculate line-level impact, and render truthful prices in real time. Cart totals now match checkout in the critical scenarios the system handles.

Key technical decisions

State signature tracking. Rather than reprocessing on every cart change, the system tracks a signature of the current discount plus items. If nothing has changed, recalculation is skipped — preventing DOM thrashing on high-traffic carts.

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, allocates the percentage across the paid items only, and presents both discount types clearly.

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.
• RebuyCartCallbacks — the renderer. Owns price DOM snapshotting, sale/compare-at rendering, proportional discount display, revert behavior when discount state changes, and subtotal reconciliation.
• 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.
• Adjacent modules: a URL / code discount input manager and bundle-builder UI updates.

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.

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 — 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 and discount-mode conflicts.

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.