Cart Rules Engine: Line Item & Cart Conjunction Logic

Showing irrelevant upsells annoys shoppers and drags down conversion rates. If a customer is buying a pair of running shoes, showing them a winter parka in the cart feels out of touch. But showing them moisture-wicking running socks or anti-blister insoles feels helpful and converts at 25%+.

Supercart includes a multi-dimensional Rules Engine that allows you to display any block (upsells, free gifts, discount incentives, or special messages) only when the customer’s cart matches your exact conditions.

---

1. The Two Rule Groups

Supercart separates conditions into two distinct logic groups:

┌────────────────────────────────────────────────────────┐
│ GROUP 1: Line Item Rules                               │
│ Evaluates individual products inside the basket        │
│ (Product Title, Handle, Collection, Vendor, Type, Tag) │
└──────────────────────────┬─────────────────────────────┘
                           │
                 [ AND / OR Conjunction ]
                           │
┌──────────────────────────▼─────────────────────────────┐
│ GROUP 2: Cart-Level Rules                              │
│ Evaluates aggregate basket state                       │
│ (Cart Subtotal, Total Item Count, Weight, Currency)    │
└────────────────────────────────────────────────────────┘

---

2. Group 1: Line Item Conditions

Line item rules evaluate the specific items in the customer’s basket:

Property	Supported Operators	Example Use Case
Product Handle / Title	Equals, Contains, Does not contain	Target buyers of a specific flagship item (e.g. leather-jacket).
Collection	Belongs to collection, Does not belong	Display shoe trees only if cart has items from Footwear.
Product Type	Equals, Contains	Target all items classified as Fragrance or Electronics.
Vendor	Equals, Contains	Target third-party brands with unique shipping policies.
Product Tag	Contains, Does not contain	Target products tagged oversized, hazmat, or final-sale.
SKU	Equals, Starts with	Target specific variants or regional inventory SKUs.

All Products vs. Any Product (single_item_match)

• “ANY Cart Product” (Default): The rule passes if at least one item in the basket matches the condition.
• “ALL Cart Products”: The rule passes only if every single item in the basket matches the condition (ideal for strict category-wide promotions).

---

3. Group 2: Cart-Level Conditions

Cart rules evaluate aggregate basket metrics:

Property	Supported Operators	Example Use Case
Cart Subtotal ($)	Greater than, Less than, Equal to	Display an exclusive $10 upsell only when cart total exceeds $75.
Total Items Count	Greater than, Less than, Equal to	Trigger “Buy 3, Get 1 Free” prompts when count is 2.
Total Weight (lbs/kg)	Greater than, Less than	Require heavy freight handling surcharge when weight > 25 lbs.
Cart Currency	Equals	Show UK-specific bundles only when currency is GBP.

---

4. Conjunction Logic: ALL vs. ANY

You have granular control over how conditions combine:

• ALL Conditions (Conjunctive AND): Every single configured rule must evaluate to true for the block to display.
• ANY Condition (Disjunctive OR): If any single configured rule evaluates to true, the block displays immediately.

[!NOTE] Default Behavior: When a block has no cart rules configured, it is considered unrestricted and displays to all shoppers unconditionally.

---

5. Real-World Merchandising Blueprints

Blueprint A: Complementary Accessory Upsell

• Goal: Sell a $15 leather conditioner.
• Group 1 (Line Items): Collection contains “Leather Goods”.
• Group 2 (Cart Total): Cart Subtotal greater than $50.00.
• Result: Shoppers buying leather bags or jackets over $50 see a targeted 1-click leather care offer right above the checkout button.

Blueprint B: High-Tier Free Gift Unlock

• Goal: Automatically award a free branded travel pouch.
• Group 1 (Line Items): Product Tag does not contain “wholesale”.
• Group 2 (Cart Total): Cart Subtotal greater than $120.00.
• Result: Retail shoppers who cross the $120 threshold unlock the free gift; wholesale accounts are safely excluded.

---

6. Sub-Millisecond Speed Architecture

Unlike legacy cart apps that ping external servers every time an item is added, Supercart evaluates rules entirely inside the browser:

• Product tag and collection metadata are cached in sessionStorage under sc:line_tags_{variant_id}.
• Complex multi-rule expressions resolve in 0.4 milliseconds.
• Upsell blocks appear smoothly without loading spinners or layout shifts.