Cart-Level Conditions

Cart-level conditions are evaluated once against the overall state of the cart. They determine whether a rule group’s conditions are met based on customer attributes, cart totals, and cart metadata. When a cart-level condition fails in AND logic, the entire rule group is skipped without evaluating any product-level conditions.

customerTag

Check whether the current customer has specific tags assigned to their account.

Operators: hasAny, hasNone

Fields:

Field	Type	Description
`tags`	`string[]`	List of customer tags to check against

Supported Functions: Conditional, Tiered, BXGY, Bundle (all 4)

Customer tags are resolved via the cart query variable at runtime. The comparison is case-insensitive.

hasAny — The condition passes if the customer has at least one of the specified tags.
hasNone — The condition passes if the customer has none of the specified tags.

{
  "type": "customerTag",
  "operator": "hasAny",
  "tags": ["VIP", "wholesale"]
}

{
  "type": "customerTag",
  "operator": "hasNone",
  "tags": ["restricted", "blocked"]
}

customerIsAuthenticated

Check whether the customer is logged in (authenticated) or browsing as a guest.

Operators: None (equality comparison)

Fields:

Field	Type	Description
`boolValue`	`boolean`	`true` to require authentication, `false` to require guest

Supported Functions: Conditional

This condition uses a simple boolean comparison rather than an operator field. Set boolValue to true to match only logged-in customers, or false to match only guest visitors.

{
  "type": "customerIsAuthenticated",
  "boolValue": true
}

{
  "type": "customerIsAuthenticated",
  "boolValue": false
}

customerOrderCount

Check the total number of orders the customer has placed historically.

Operators: All numeric operators (greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equals, between)

Fields:

Field	Type	Description
`value`	`number`	The threshold value for comparison
`valueTo`	`number`	Upper bound (required only for `between` operator)

Supported Functions: Conditional

This condition is useful for creating loyalty-based discounts or first-purchase incentives. The order count reflects the customer’s complete order history.

{
  "type": "customerOrderCount",
  "operator": "greaterThan",
  "value": 5
}

{
  "type": "customerOrderCount",
  "operator": "equals",
  "value": 0
}

{
  "type": "customerOrderCount",
  "operator": "between",
  "value": 1,
  "valueTo": 10
}

customerTotalSpent

Check the total amount the customer has spent across all historical orders.

Operators: All numeric operators (greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equals, between)

Fields:

Field	Type	Description
`value`	`number`	The threshold value for comparison (in shop currency)
`valueTo`	`number`	Upper bound (required only for `between` operator)

Supported Functions: Conditional

The total spent value is expressed in the shop’s base currency. This condition enables spend-tier discounts where customers who have spent more receive better pricing.

{
  "type": "customerTotalSpent",
  "operator": "greaterThanOrEqual",
  "value": 500
}

{
  "type": "customerTotalSpent",
  "operator": "between",
  "value": 100,
  "valueTo": 999.99
}

cartSubtotal

Check the current cart’s subtotal amount.

Operators: All numeric operators (greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equals, between)

Fields:

Field	Type	Description
`value`	`number`	The threshold value for comparison (in cart currency)
`valueTo`	`number`	Upper bound (required only for `between` operator)

Supported Functions: Conditional, Tiered, BXGY, Bundle (all 4)

The cart subtotal is the sum of all line item prices before any discounts are applied. This is one of the most commonly used conditions for minimum-spend thresholds.

{
  "type": "cartSubtotal",
  "operator": "greaterThan",
  "value": 100
}

{
  "type": "cartSubtotal",
  "operator": "between",
  "value": 50,
  "valueTo": 200
}

cartTotalQuantity

Check the total number of items across all lines in the cart.

Operators: All numeric operators (greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equals, between)

Fields:

Field	Type	Description
`value`	`number`	The threshold value for comparison
`valueTo`	`number`	Upper bound (required only for `between` operator)

Supported Functions: Conditional, Tiered, BXGY, Bundle (all 4)

This counts the total quantity of all items, not the number of distinct line items. For example, a cart with 3 units of Product A and 2 units of Product B has a total quantity of 5. To check distinct line items instead, use cartLineCount.

{
  "type": "cartTotalQuantity",
  "operator": "greaterThanOrEqual",
  "value": 3
}

{
  "type": "cartTotalQuantity",
  "operator": "between",
  "value": 5,
  "valueTo": 20
}

cartLineCount

Check the number of unique line items in the cart.

Operators: All numeric operators (greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equals, between)

Fields:

Field	Type	Description
`value`	`number`	The threshold value for comparison

Supported Functions: Conditional

Unlike cartTotalQuantity which sums all item quantities, cartLineCount counts the number of distinct line items. A cart with 3 units of Product A and 2 units of Product B has a line count of 2 regardless of quantities.

{
  "type": "cartLineCount",
  "operator": "greaterThan",
  "value": 1
}

{
  "type": "cartLineCount",
  "operator": "greaterThanOrEqual",
  "value": 3
}

market

Check the customer’s market based on their country code.

Operators: isAny, isNone

Fields:

Field	Type	Description
`countryCodes`	`string[]`	List of ISO 3166-1 alpha-2 country codes

Supported Functions: Conditional, Tiered, BXGY, Bundle (all 4)

Country codes must be provided in ISO 3166-1 alpha-2 format (two uppercase letters). The customer’s market is determined by Shopify’s market resolution at checkout.

isAny — The condition passes if the customer’s country matches any of the listed codes.
isNone — The condition passes if the customer’s country matches none of the listed codes.

{
  "type": "market",
  "operator": "isAny",
  "countryCodes": ["US", "CA", "GB"]
}

{
  "type": "market",
  "operator": "isNone",
  "countryCodes": ["RU", "BY"]
}

cartAttribute

Check custom cart attributes (key-value pairs set on the cart object).

Operators: exists, notExists, equals, contains

Fields:

Field	Type	Description
`key`	`string`	The cart attribute key to check
`values`	`string[]`	Values to compare against (for `equals` and `contains` operators)

Supported Functions: Conditional

Cart attributes are custom key-value pairs that can be attached to the cart by the storefront or third-party apps. This condition inspects those attributes to enable flexible, integration-driven discount rules.

exists — Passes if the attribute key is present on the cart (regardless of value).
notExists — Passes if the attribute key is not present on the cart.
equals — Passes if the attribute value exactly matches one of the provided values.
contains — Passes if the attribute value contains one of the provided values as a substring.

{
  "type": "cartAttribute",
  "key": "gift_wrapping",
  "operator": "equals",
  "values": ["true"]
}

{
  "type": "cartAttribute",
  "key": "referral_source",
  "operator": "contains",
  "values": ["instagram", "tiktok"]
}

{
  "type": "cartAttribute",
  "key": "loyalty_id",
  "operator": "exists"
}