# Quantity rules

URL: https://docs.sparklayer.io/help/storefront/quantity-rules
Applies to: Shopify, BigCommerce, WooCommerce, Magento

Control how many units B2B customers can order: set pack sizes, minimum and maximum quantities per variant or product, and order limits per customer group.

> **Quick summary**
>
> - Quantity rules control how many units of a product B2B customers can order: a **pack size** (for example, multiples of 6) or a **minimum** or **maximum** quantity.
> - The basic way: turn on SparkLayer's metafields once, then type a number into the **B2B - Pack Size** (or minimum or maximum) field on each product variant.
> - For a limit on the whole order, such as a minimum order value or number of items, use [order limits](#order-limit-rules) on a customer group instead. No metafields needed.
> - Available on every plan. Wix doesn't support metafields, so product quantity rules aren't available on Wix.

## Set a pack size

A pack size means a product must be ordered in multiples of a number, for example 6, 12, 18. With a pack size of 6, the quantity selector moves in steps of 6. It's also called a quantity increment.

**Shopify:**

1. **Turn on the pack size field (once).** In SparkLayer, go to **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. Make sure **B2B - Pack Size** is enabled. SparkLayer adds the field to your Shopify variants.

   **More detail**

   See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md). To create the field yourself instead, go to **Settings > Custom data > Variants** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/productvariant/metafields)) in the Shopify admin and add a definition:

   | Field                 | Value                                   |
   | --------------------- | --------------------------------------- |
   | **Name**              | Any name, for example `B2B - Pack Size` |
   | **Namespace and key** | `sparklayer.pack_size`                  |
   | **Type**              | **Integer**, **One value**              |

2. **Enter the pack size.** Open the product in the Shopify admin, select a variant and enter the pack size in the **B2B - Pack Size** field, for example `6`.

3. **Save** the product.

4. **Check it.** Sign in to your store as a B2B customer and open the product. The quantity selector moves in steps of 6, and a **Qty rules apply** link under it says "This product comes in pack sizes of 6".

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick **B2B - Pack Size** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

> **Common mistake: wrong namespace**
>
> If you create the field yourself, its **Namespace and key** must read exactly `sparklayer.pack_size`. Shopify fills in `custom.` for you, and SparkLayer never reads that. See [Add metafields by hand](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#add-metafields-by-hand).

**Other platforms:**

1. **Add the field.** Add a variant-level product field with the values below. See your platform's guide for where to add it: [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md), [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/metafields.md) or [Magento](https://docs.sparklayer.io/help/platforms/magento/metafields.md).

   | Field                | Value                           |
   | -------------------- | ------------------------------- |
   | **Custom data type** | Variant-level (products)        |
   | **Metafield type**   | `integer`                       |
   | **Namespace**        | `sparklayer`                    |
   | **Key**              | `pack_size`                     |
   | **Value**            | A whole number, for example `6` |

2. **Turn it on in SparkLayer.** Go to **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**, then enable the pack size. SparkLayer doesn't read a field until it's enabled, even if it already exists in your store.

3. **Check it.** Sign in to your store as a B2B customer and open the product. The quantity selector moves in steps of your pack size.

For more detail, see the [developer docs](https://docs.sparklayer.io/developers.md).

Every quantity rule is set on the product variant, even when the product has a single variant. To give all of a product's variants the same rule, enter it on each one, or use the bulk editor.

## Set minimum and maximum quantities

Minimum and maximum quantities stop customers ordering too few or too many units. Each one has its own field, and they work the same way as the pack size:

| Rule | What it does | Field (metafield key) |
| --- | --- | --- |
| **Minimum per variant** | Each variant (for example each colour) must be ordered in at least this quantity. | `min_order_quantity` |
| **Maximum per variant** | Each variant can be ordered in at most this quantity. | `max_order_quantity` |
| **Minimum per product** | The total across all of a product's variants must be at least this quantity. | `min_order_parent_quantity` |
| **Maximum per product** | The total across all of a product's variants can be at most this quantity. | `max_order_parent_quantity` |

1. Turn on the field for your rule. On Shopify, go to **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. On other platforms, add it first using the [metafield reference](#metafield-reference), then enable it there.
2. On each variant, enter a whole number, for example `6`, `12` or `20`. Product-wide rules are still entered on each variant.
3. Save the product.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**BigCommerce only:**

On BigCommerce, you can also use BigCommerce's own [Minimum and Maximum Order Quantity](https://support.bigcommerce.com/s/article/Minimum-Maximum-Purchase-Quantity) product setting. SparkLayer applies it to each variant, so each variant gets its own minimum or maximum, even though BigCommerce sets it on the product.

## What customers see

When a product has a quantity rule, the [product interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) apply it as customers build their order:

- The quantity selector follows the rule. If a customer types a quantity that doesn't fit the pack size, it updates to fit.
- A **Qty rules apply** link appears under the quantity selector. It opens the rule, such as "This product comes in pack sizes of 6".
- With a pack size, a pack price shows under the unit price, for example **Pack (6): US$71.40**.

### Show or hide the pack price

The pack price is the unit price multiplied by the number of items in a pack. It shows in the product detail interface.

To hide the pack price, you or your developer add this line to your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md):

```css
--spark-pdp-pack-size: none;
```

To change the pack price wording without code, add a translation override for the key `pdp.price.pack-size` at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. In the text, `{packSize}` is the pack size and `{price}` the pack price.

**For developers: set the text in the Core Script**

Set it in your Core Script instead (see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md)):

```javascript title="Core Script"
translations: {
  en: {
   "pdp.price.pack-size": "Pack ({packSize}): {price}",
  }
},
```

### Hide the "Qty rules apply" message

To hide the link, you or your developer add this line to your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md):

```css
--spark-product-qty-rules-display: none;
```

## Set order limits

Order limits apply to the whole order rather than to one product, and customers can't check out until their order meets them. They're rules on a [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md), so they don't need metafields. There are two:

| Rule | What it limits | Example |
| --- | --- | --- |
| **Order total limits** | The order total: a minimum and, if you want one, a maximum, per currency. | The order must be at least $250. |
| **Order quantity limits** | The number of items in the order: a minimum or a maximum. | The order must have at least 12 items. |

To set them:

1. Go to **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app and click a group's name (or **Edit** on the base customer group, for every group).
2. Under **Inherited rules**, click **+ Override** next to **Order total limits** or **Order quantity limits** (on the base group, **+ Customize**).
3. For **Order total limits**, choose a **Currency** and enter a **Minimum order total** and, if you want one, a **Maximum (optional)**. To set a limit in another currency, click **Add order total limit**. To remove one, click the bin icon next to it. For **Order quantity limits**, click **Configure**.
4. Click **Save**.

**More detail**

- Order totals are **net**, which means they exclude tax. With [tax-inclusive price display](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices) on, they're checked against the gross total the customer sees instead.
- You can also enter a minimum order value when you [create a customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#create-a-customer-group). It becomes the group's **Order total limits** rule.
- Groups follow the base customer group's limits until you override them. Click **Reset** on the rule to hand it back.
- For a minimum, maximum or pack size on one product, use the [product quantity rules](#set-minimum-and-maximum-quantities) above instead.

When a customer's order doesn't meet a limit, the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) shows a message such as "Your order must be more than $100 to meet the order requirements" and **Checkout** is unavailable until they change their order.

### Change the order limit messages

To change the wording without code, add a translation override for the message's key, shown below, at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md). In the text, `{amount}` is the order total limit, and `{minimum}` and `{maximum}` the number of items.

**For developers: set the text in the Core Script**

For order total limits:

```javascript title="Core Script"
translations: {
  en: {
    "cart.validation-message.minimum-order-totals": "Your order must be more than {amount} to meet the order requirements.",
    "cart.validation-message.maximum-order-totals": "Your order must be less than {amount} to meet the order requirements.",
  }
},
```

For order quantity limits:

```javascript title="Core Script"
translations: {
  en: {
    "cart.validation-message.minimum-order-item-quantity": "Your order must have at least {minimum} items to meet the order requirements.",
    "cart.validation-message.maximum-order-item-quantity": "Your order must not exceed {maximum} items to meet the order requirements.",
  }
},
```

## Quantity pricing (tiered pricing)

Quantity pricing gives lower unit prices for larger quantities, for example buy 1 for $10 or 10 for $8. See [Quantity pricing and settings](https://docs.sparklayer.io/help/pricing/quantity-pricing.md).

Quantity pricing sets a minimum too: the lowest quantity tier in the customer's price list is the smallest quantity they can order. If a product's first tier is 50+, customers see "Unavailable in selected quantity" below 50. To let them order fewer, add a price from a quantity of 1.

## Unit of measure pricing

Unit of measure pricing sets prices for units such as boxes, cartons or pallets. See [unit of measure pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md#set-up-unit-of-measure-pricing).

## Set different rules for each customer group

Everything above applies to all your B2B customers. To give a customer group its own pack size, minimum or maximum, use the `sparklayer.settings` field on the variant ([product settings](https://docs.sparklayer.io/help/storefront/product-settings.md)). For example, most customers could buy in packs of 6 and a `tier-2` group in packs of 12.

1. Find each group's handle: open the group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app and look under **Handle (or ID)**.
2. In the form below, enter each group's handle and its rules. It writes the value for you. Use `base` for the rules everyone else gets.
3. Click **Copy**, paste the value into the variant's `sparklayer.settings` field and save. To give many variants the same rules, paste it into each row in Shopify's bulk editor.

**Field details, if you add the field by hand**

| Field | Value |
| --- | --- |
| **Custom data type** | Variants ([Shopify](https://admin.shopify.com/settings/custom_data/productvariant/metafields)), or variant-level product fields on other platforms |
| **Metafield type** | `JSON` |
| **Namespace** | `sparklayer` |
| **Key** | `settings` |
| **Value** | One entry per customer group, for example `[{"customer_group":"base","pack_size":6},{"customer_group":"tier-2","pack_size":12}]` |

See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md) for everything this field can do.

> **Once a variant has settings, its other quantity fields are ignored**
>
> If a variant has any `sparklayer.settings` value, even one that only hides it from a group, SparkLayer ignores its individual fields such as `sparklayer.pack_size`. Put the pack size, minimum and maximum inside the JSON instead.

### Which rule wins

SparkLayer uses the first of these that applies to the customer:

1. **The customer's group entry in `sparklayer.settings`.** It overrides the `base` entry for that group.
2. **The `base` entry in `sparklayer.settings`.** It's the default for every customer group.
3. **The individual fields**, such as `sparklayer.pack_size` and `sparklayer.max_order_quantity`, but only when the variant has no `sparklayer.settings` value.

For example:

```json
[
  { "customer_group": "base", "pack_size": 50 },
  { "customer_group": "retail-partners", "pack_size": 10, "display": true },
  { "customer_group": "distributors", "display": false }
]
```

Every group buys in packs of 50, except `retail-partners`, who buy in packs of 10. `distributors` don't see the product. A `sparklayer.pack_size` on the same variant is ignored. See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md#which-rule-wins).

## Metafield reference

This reference is for whoever sets up your product data. All keys use the namespace `sparklayer` and are set on product variants. On Shopify, the custom data type is [Variants](https://admin.shopify.com/settings/custom_data/productvariant/metafields). On other platforms, use variant-level product fields.

| Key | Type | Value |
| --- | --- | --- |
| `pack_size` | `integer` | A whole number, for example `6` |
| `min_order_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `min_order_parent_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `max_order_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `max_order_parent_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `settings` | `JSON` | One entry per customer group. See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md). |

## Troubleshooting

**Diagnose: Pack sizes or quantity limits not applying?** Check the metafields behind your product rules.

1. **Are SparkLayer’s metafields turned on in SparkLayer?** SparkLayer doesn’t read metafields until they’re configured in the Metafields card. Where to look: Integrations > Platform (SparkLayer).
   - Yes: go to question 2
   - No / not sure: go to fix A (Turn on SparkLayer’s metafields)
2. **How is the rule set up on the product?** Single metafields, such as `sparklayer.pack_size`, set one rule for everyone. The `sparklayer.settings` metafield sets rules per customer group. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Single metafields: go to question 3
   - The sparklayer.settings metafield: go to question 4
   - Not sure: go to question 3
3. **Does the variant also have a `sparklayer.settings` metafield with a value?** When it does, it takes priority over the single metafields. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to fix B (Put the rule inside the settings metafield)
   - No: go to question 5
4. **Does the JSON have an entry for this customer’s group, or a `base` entry?** `base` is the default for every group. An entry for a group overrides it. Use the group’s handle, for example `vip`. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to question 6
   - No: go to fix C (Add an entry for the group)
5. **Is the metafield set on the variant, not the product?** Rules are read per variant, even when a product has only one variant. Where to look: Settings > Custom data > Variants (Shopify admin).
   - Yes, on the variant: go to question 7
   - No, on the product: go to fix D (Move the metafield to the variant)
6. **Is the JSON correctly formatted, with straight quotes?** A missing quote, comma or bracket breaks every rule in the value. Paste it into a JSON checker if unsure.
   - Yes: go to question 8
   - No / not sure: go to fix E (Fix the JSON)
7. **Does the definition’s namespace and key read exactly as documented, such as `sparklayer.pack_size`?** In Shopify the namespace and key are one field. Any other spelling is ignored. Where to look: Settings > Custom data > Variants (Shopify admin).
   - Yes: go to question 9
   - No / not sure: go to fix F (Correct the metafield definition)
8. **Does the rule work on other products, just not this one?** Products on a different theme template may not have SparkLayer’s product widget.
   - Yes: go to fix G (Add SparkLayer to this product’s template)
   - No, it doesn’t work anywhere: go to question 10
9. **Does this variant have a whole number entered?** An empty value means no rule. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to question 8
   - No: go to fix H (Add a value to the variant)
10. **Are you testing as a signed-in customer in the group you expect?** Rules follow the customer’s group.
   - Yes: go to fix I (Everything checks out)
   - No / not sure: go to fix J (Check the customer’s group)

**Fixes**

- **A. Turn on SparkLayer’s metafields** In the Metafields card, click Configure and enable the metafields you use. SparkLayer adds their definitions to Shopify for you. Where: Integrations > Platform (SparkLayer). See [Shopify metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).
- **B. Put the rule inside the settings metafield** When a variant has `sparklayer.settings`, its JSON takes priority and the single metafields are ignored. Add the rule, such as `pack_size`, to each group’s entry in the JSON. Where: Products > select a variant > Metafields (Shopify admin). See [Which rule wins](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **C. Add an entry for the group** Add an entry with the group’s handle and its rule, or a `base` entry to set a default for everyone. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **D. Move the metafield to the variant** Create the definition under Variants, then add the value to each variant. Where: Settings > Custom data > Variants (Shopify admin).
- **E. Fix the JSON** Correct the formatting and save. Copy an example from Quantity rules as a starting point. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **F. Correct the metafield definition** Use the exact namespace and key from Quantity rules, such as `sparklayer.pack_size` with the Integer type. A definition under another namespace is ignored. Where: Settings > Custom data > Variants (Shopify admin). See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **G. Add SparkLayer to this product’s template** The product uses a template without SparkLayer’s product widget, so its rules can’t show. Switch it to your main template, or send us the template name and we’ll add the widget. Where: Products > select the product (Shopify admin).
- **H. Add a value to the variant** Enter a whole number, for example 6, and save. Each variant needs its own value. Where: Products > select a variant > Metafields (Shopify admin).
- **I. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **J. Check the customer’s group** Rules depend on the customer’s group, so a missing or wrong group tag stops them applying. Next: Wrong prices, payment methods or shipping for a customer?

## FAQs

**What happens if a customer enters a quantity that doesn't fit the pack size?**

The quantity updates to fit the pack size. Products added with a [1-click ordering button](https://docs.sparklayer.io/help/storefront/product-display.md#add-1-click-ordering-buttons-spark-buttons) are rounded up to the next full pack.

**Can customers add a set of products in one click?**

Yes. Spark Buttons add a set of SKUs and quantities to an order in one click. See [1-click ordering buttons](https://docs.sparklayer.io/help/storefront/product-display.md#add-1-click-ordering-buttons-spark-buttons).

**Can I change the quantity rule messages?**

Yes. The messages are translations such as `global.product-settings.pack-size` and `min-order-quantity`. See [Change text that contains variables](https://docs.sparklayer.io/help/storefront/languages-and-international.md#change-text-that-contains-variables).