Cart Line Groups

Learn how to use cart line groups to filter cart items based on conditions like tags, collections, and metafields for targeted discounts and calculations.

Cart Line Groups

Cart line groups let you filter products in your customer’s cart based on conditions. Once filtered into groups, you can apply discounts, count quantities, or perform calculations on those specific items rather than the entire cart.

What Are Cart Line Groups?

A cart line group is a named filter that selects cart items matching specific criteria. For example:

  • “Sale Items” - products with a specific tag
  • “Premium Products” - items above a certain price
  • “Summer Collection” - products from a particular collection
  • “Clearance” - items with a clearance metafield

Groups are created using the Define Cart Line Groups block, which filters cart items based on product properties, tags, collections, metafields, and more.

Why Use Cart Line Groups?

Targeted Discounts

Apply discounts only to specific products:

  • “20% off all sale items” - discount only the “Sale Items” group
  • “Buy 2 shirts, get 1 accessory free” - use separate groups for shirts and accessories

Quantity Logic

Count items within specific groups:

  • “Buy 3 or more premium items for 15% off”
  • “Free shipping when you have 5+ clearance items”

Exclusions

Exclude certain products from promotions:

  • Apply order discount but exclude gift cards
  • Offer storewide sale but exclude new arrivals

Cross-Sell Promotions

Create “Buy X, Get Y” offers across product categories:

  • “Buy any shoes, get socks 50% off”
  • “Purchase a laptop, get accessories discounted”

How Cart Line Groups Work

1. Define Groups First

Before using groups in discounts or other actions, you must create them using the Define Cart Line Groups block. This block:

  • Evaluates each item in the cart
  • Checks if items match your specified conditions
  • Assigns matching items to named groups

2. Reference Groups in Actions

Once defined, groups can be referenced in:

  • Discount blocks - apply discounts to specific groups
  • Count Items - count quantities within groups
  • Sum Values - calculate totals for grouped items
  • Order Discounts - exclude groups from order-level discounts

3. Multiple Groups Per Item

A single cart item can belong to multiple groups. For example, a “Red Summer Dress” might be in both:

  • “Summer Collection” group
  • “Dresses” group
  • “Sale Items” group

Setting Up Cart Line Groups

Step 1: Add the Define Cart Line Groups Block

In your function flow, add the Define Cart Line Groups block before any actions that need to reference groups.

Step 2: Configure Group Conditions

For each group, specify:

  • Group Name: A descriptive identifier (e.g., “SALE_ITEMS”, “PREMIUM”)
  • Conditions: Rules that determine which products belong to the group

Step 3: Use Groups in Subsequent Actions

Reference your groups by name in discount blocks, counters, and other actions.

Using Groups with Discounts

Selecting Target Groups

When configuring a discount, you can:

  • Leave empty: Discount applies to all eligible items in the cart
  • Select specific groups: Discount only applies to items in those groups
  • Select multiple groups: Discount applies to items in ANY of the selected groups

Example: Category-Specific Sale

Group: "SUMMER_COLLECTION"
Discount: 25% off
Result: Only summer collection items receive the discount

Example: Multi-Category Promotion

Groups: "SUMMER_COLLECTION" + "CLEARANCE"
Discount: 30% off
Result: Items from either collection receive the discount

Excluding Groups from Order Discounts

Order discounts can exclude specific groups from their calculation:

Order Discount: 10% off entire order
Excluded Groups: "GIFT_CARDS", "FINAL_SALE"
Result: Gift cards and final sale items don't count toward the discount

Advanced Group Settings

Beyond a name and conditions, each group has optional settings (in the group’s Settings section) that refine which items it selects and in what order.

Source Items (Advanced plan)

By default a group filters the whole cart. Instead, you can source its items from another group defined in an earlier Define Cart Line Groups block, so the group only filters within that group’s items — multi-step filtering.

  • All cart line items (default): conditions are evaluated against every item in the cart.
  • Another group: for example, a “SALE_ITEMS” group can use “ELECTRONICS” as its source to match only electronics that are on sale.

Notes:

  • Sources can be chained — a group whose source itself has a source filters through the whole chain.
  • If the source group ends up empty (or its block didn’t run on the current path), this group is empty too — it never falls back to the whole cart.

Item Ordering

Controls the order of items inside the group before any limit is applied:

  • Cart order (default)
  • Price: low to high
  • Price: high to low

Because ordering happens before the item limit, it decides which items survive the limit — for example, “Price: high to low” with a limit of 1 selects the single most expensive matching item.

Item Limit

Keeps at most a set number of items from the group (after ordering). Leave it empty for no limit.

  • The limit counts individual items (units), not cart lines. A limit of 1 on a cart line with a quantity of 3 keeps a single unit of that line, not all three. The limit fills lines in order and caps the line that crosses the limit.
  • Combine Item Ordering and Item Limit to express rules like “the 3 most expensive matching items” or “the single cheapest item”.
  • A discount that targets the group with its own ordering or limit overrides these per-group values — the group’s settings act as the default when the discount leaves them unset.

Note: Item Ordering and Item Limit apply when building discount functions. They aren’t shown for promotion functions, where groups feed item counts and totals that don’t depend on order or a per-item cap.

Example: Discount Only the Most Expensive Item

Group: "TOP_ITEM"
- Unit Price greater than 50
- Item Ordering: Price: high to low
- Item Limit: 1

Discount: 20% off → Target group: TOP_ITEM
Result: Only one unit of the single most expensive qualifying item is
discounted, even if that line's quantity is greater than one.

Best Practices

Naming Conventions

  • Use clear, descriptive names: “PREMIUM_PRODUCTS” not “GROUP1”
  • Be consistent with naming style (uppercase, underscores)
  • Consider using prefixes for related groups: “CAT_SHOES”, “CAT_ACCESSORIES”

Placement in Flow

  • Define groups at the beginning of your function flow
  • Create groups before any actions that reference them
  • Avoid creating unnecessary groups - only create filters you need

Testing

  • Verify products are correctly assigned to groups
  • Test with carts containing items from multiple groups
  • Check edge cases: items in multiple groups, items in no groups

Common Patterns

Tag-Based Groups

Filter products by Shopify tags:

  • “Sale” tag → “SALE_ITEMS” group
  • “New Arrival” tag → “NEW_ARRIVALS” group
  • “Clearance” tag → “CLEARANCE” group

Collection-Based Groups

Filter products by collection membership:

  • Summer 2024 collection → “SUMMER_COLLECTION” group
  • Best Sellers collection → “BESTSELLERS” group

Price-Based Groups

Filter products by price range:

  • Items over $100 → “PREMIUM” group
  • Items under $25 → “BUDGET” group

Metafield-Based Groups

Filter products by custom metafield values:

  • Products with discount_eligible: true → “DISCOUNTABLE” group
  • Products with tier: gold → “GOLD_TIER” group

Troubleshooting

Group Not Matching Expected Products

  • Verify the condition logic in Define Cart Line Groups
  • Check that product data (tags, metafields) is correctly set in Shopify
  • Test with specific products you expect to match

Discount Not Applying to Group

  • Ensure the group is defined BEFORE the discount action in your flow
  • Verify the group name matches exactly (case-sensitive)
  • Check that products in the cart actually belong to the group

Products in Wrong Groups

  • Review your group conditions for overlapping criteria
  • Check the order of group definitions if using complex logic
  • Verify metafield values are what you expect