> For the complete documentation index, see [llms.txt](https://responsive-media.gitbook.io/advanced-free-shipping/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://responsive-media.gitbook.io/advanced-free-shipping/conditions-cart-and-order/cart-quantity.md).
# Cart Quantity
## Overview
The **Cart Quantity** condition applies discounts based on the total number of items in the customer's cart. Each line item's quantity is summed to get the total.
## How Quantity is Calculated
```
Cart Quantity = Sum of all line item quantities
```
**Example cart**:
* Product A × 2
* Product B × 1
* Product C × 3
**Cart Quantity**: 2 + 1 + 3 = **6 items**
{% hint style="info" %}
Cart Quantity counts individual items, not unique products. If a customer adds 5 of the same product, that counts as 5 items.
{% endhint %}
## Available Operators
All numeric operators are available:
* **Is greater than** - More than X items
* **Is less than** - Fewer than X items
* **Is equal to** - Exactly X items
* **Is at least** - X or more items (most common)
* **Is at most** - X or fewer items
## Common Use Cases
### Bulk Order Discount
**Free shipping when buying 5+ items**
**Configuration**:
* Condition: Cart quantity **is at least** 5
* Target: All shipping rates → Free
**How it works**:
* 3 items in cart → No discount
* 5 items in cart → Free shipping ✓
* 10 items in cart → Free shipping ✓
{% hint style="info" %}
This encourages customers to add more items to their cart, increasing average order value.
{% endhint %}
### Small Order Fee Waiver
**Free shipping for orders with 3+ items**
**Configuration**:
* Condition: Cart quantity **is at least** 3
* Target: All shipping rates → Free
**Use case**: Reward customers who buy multiple items instead of single items.
### Maximum Quantity Discount
**Discounted shipping for small orders only**
**Configuration**:
* Condition: Cart quantity **is at most** 2
* Target: All shipping rates → $2 flat rate
**Use case**: Encourage small, frequent orders or clear single-item inventory.
### Exact Quantity Promotion
**"Buy exactly 6 items, get free shipping"**
**Configuration**:
* Condition: Cart quantity **is equal to** 6
* Target: All shipping rates → Free
**Use case**: Gamification or six-pack promotions.
## Combining with Other Conditions
### Quantity + Value
**Free shipping for 5+ items OR $50+ cart**
* Rule Group 1:
* Condition: Cart quantity **is at least** 5
* Rule Group 2:
* Condition: Cart total **is at least** $50
Either 5 items OR $50 triggers free shipping.
### Quantity + Product
**Free shipping when buying 3+ of a specific product**
* Condition 1: Product **contains** "T-Shirt"
* Condition 2: Cart quantity **is at least** 3
{% hint style="info" %}
This counts ALL items in cart. For quantity of specific products/collections, use Collection Item Quantity instead.
{% endhint %}
### Quantity + Location
**Different quantity thresholds by region**
* Rule Group 1 (US):
* Condition 1: Country **is** US
* Condition 2: Cart quantity **is at least** 3
* Rule Group 2 (International):
* Condition 1: Country **is not** US
* Condition 2: Cart quantity **is at least** 5
## Examples by Use Case
{% tabs %}
{% tab title="Bulk Purchase Reward" %}
**Goal**: Encourage customers to buy in bulk
**Configuration**:
* Condition: Cart quantity **is at least** 10
* Discount: Free shipping
**Result**: Customers buying 10+ items get free shipping, encouraging bulk orders.
{% endtab %}
{% tab title="Tiered by Quantity" %}
**Goal**: Graduated discounts based on quantity
**Create multiple discounts**:
1. 3-5 items: 25% off shipping
* Condition: Cart quantity **is at least** 3
2. 6-9 items: 50% off shipping
* Condition: Cart quantity **is at least** 6
3. 10+ items: Free shipping
* Condition: Cart quantity **is at least** 10
{% endtab %}
{% tab title="Subscription Box" %}
**Goal**: Free shipping on subscription boxes (6 items)
**Configuration**:
* Condition 1: Cart quantity **is equal to** 6
* Condition 2: Has subscription **contains subscription**
* Discount: Free shipping
Perfect for monthly subscription boxes with fixed item counts.
{% endtab %}
{% tab title="Sample Order Discount" %}
**Goal**: Encourage small sample orders
**Configuration**:
* Condition: Cart quantity **is at most** 3
* Discount: $3 flat rate shipping
Makes it affordable for customers to try a few items.
{% endtab %}
{% endtabs %}
## Cart Quantity vs Collection Item Quantity
Understanding the difference:
| Feature | Cart Quantity | Collection Item Quantity |
| ----------- | ----------------- | -------------------------------------- |
| **Counts** | All items in cart | Only items from specific collection(s) |
| **Use for** | Total order size | Collection-specific promotions |
| **Example** | "Buy 5+ items" | "Buy 3+ from Winter Collection" |
**Example cart**:
* 3 items from "Winter Collection"
* 2 items from "Summer Collection"
* **Cart Quantity**: 5 items total
* **Collection Item Quantity** (Winter): 3 items
{% hint style="info" %}
Use Collection Item Quantity when you want to promote specific collections.
{% endhint %}
## Best Practices
{% hint style="info" %}
**Choose realistic thresholds.** Look at your average items per order and set thresholds slightly above that to encourage growth.
{% endhint %}
{% hint style="info" %}
**Combine with value thresholds.** Use OR logic: "5+ items OR $50+" gives customers flexibility.
{% endhint %}
{% hint style="info" %}
**Consider product types.** If you sell high-value items, quantity thresholds might not make sense. Use cart value instead.
{% endhint %}
{% hint style="warning" %}
**Quantity counts ALL items.** If you sell products with very different values (e.g., $5 accessories and $500 electronics), quantity-based discounts might not be fair. Consider using cart value instead.
{% endhint %}
## Troubleshooting
Discount not applying at expected quantity
* Verify the exact quantity in the cart (check each line item)
* Confirm you're using the right operator (≥ vs >)
* Check if you meant Collection Item Quantity instead
Discount applying to wrong orders
* Review if quantity is the right metric for your products
* Consider if cart value would be more appropriate
* Check for variant-specific quantity issues
Customers gaming the system
* If customers add low-value items to hit quantity thresholds, combine with a minimum cart value condition
* Example: "5+ items AND $30+ cart"
## Related Conditions
* **Collection Item Quantity** - Count items from specific collections
* [**Cart Total**](/advanced-free-shipping/conditions-cart-and-order/cart-total.md) - Base discounts on cart value instead
* [**Cart Weight**](/advanced-free-shipping/conditions-cart-and-order/cart-weight.md) - Base discounts on total weight
* **Product in Cart** - Require specific products
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://responsive-media.gitbook.io/advanced-free-shipping/conditions-cart-and-order/cart-quantity.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.