WooCommerce User Role Minimums


WooCommerce User Role Minimums lets you set up multiple levels of product, category, and order minimums (as well as maximums and step values) and assign them based on user role, or even by individual user.  It works in a similar fashion to the WooCommerce User Role Pricing plugin, but this is a stand-alone plugin that can be used by itself.

There are 6 sets of “minimums” that you can enable/disable individually. The first is product based minimums, where you can specify a minimum quantity, a maximum quantity, as well as a step value (force them to order in multiples of the step value), for each product and product variation. In addition to the product based minimums, you can also set Order Quantity, Order Quantity Steps, and/or Order Amount minimums that the user must meet before they are allowed to checkout. If you use both Order Quantity and Order Amount minimums, you can choose if the operator for those values is “AND” or “OR”.  “AND” means both order minimum conditions must be met to check out, while “OR” means they only need to meet one condition. Version 2.1 also adds optional maximum values for the order amount and order quantity minimums sets. If a maximum value is set (amount or quantity), that is treated as a hard limit and the customer can not checkout if they exceed the maximum value for order amount or order quantity.

Version 1.6 adds Category quantity minimums and maximums. Version 2.2 adds Category amount minimums and maximums. You define “sets” of category minimums, and then assign those to roles or individual users. Each set of category minimums can have as many categories included as you need, with each category having its own independent minimum and maximum setting. Category min/max quantities/amounts also apply to all sub-categories of that category. However, each sub-category can also have its own min/max quantities/amounts that also must be met. If you use both Category Quantity and Amount minimums, you can choose if the operator for those values is “AND” or “OR”.  “AND” means both order minimum conditions must be met to check out, while “OR” means they only need to meet one condition.

As in the WooCommerce User Role Pricing plugin, which allows you to create as many custom prices as you need, WooCommerce User Role Minimums lets you create as many minimums as you need. For each of the minimum types, you create a new minimum and give it a reference name (for your own use), such as “wholesale” or “retail”. For each product minimum you create, you will see min qty, max qty, and step inputs for every product and product variation. Once you set any of those for a product, the quantity inputs for the products will be restricted accordingly. For Order Quantity and Order Amount minimums, you specify the value for each as you create it, since those apply to the entire order and are checked on the cart and checkout pages.

In addition, you can specify the error message text for every possible error condition for product minimums and order minimums, plus you can create as many custom roles as you need by simply copying other roles and giving it a new name.

Once you have some minimums enabled and set up, you can assign which minimums you want to apply to each role or individual users. To assign minimums to an individual user, you simply edit that user in the “Users Minimums Options” section of the Edit User page from your admin dashboard. If you leave any (or all) of those individual user minimums options set to “role”, then that user’s minimums are based on what you set for their role. Minimums options for roles are set in the plugin options, which can be found under the WooCommerce menu in your admin dashboard.

Setting Up Product based Minimums

To set up product based minimums, you need to do a few things. First, on the General Settings section of the plugin options page, make sure to check the box to enable product minimums. Then, click on the “Product Minimums” tab and create a new minimum by typing in a name for the minimum in the “New Minimums Name” field of the Add a new Minimums field section. The names are only for your reference, and should be named in such a way to make it easy for you to remember which minimums go with which roles or user.

You can then check the Enable Global Values? check box if you want to set global values that will be applied to ALL products if those products do not have their own individual values set. You can set any or all of the Global Min Qty, Global Max Qty, and Global Step values.

After you submit the form to create a new minimum, it will appear in the simple list table at the top of the page, with form inputs for all values so you can edit and update the global values as well as enable/disable the global values for each set of minimums. You can also use the table to delete any product minimums you no longer need (also deletes all associated post meta, so be careful!).

Once you have a product minimums field created, you will see the name in the select box for Product Minimums on the Role Settings page, as well as on any Edit User page, so that you can assign those minimums to any roles or users you wish.

For each of the Product Minimums that you create, you will see a set of 3 new inputs for each product and product variation. For each of your custom Product Minimums, you can specify a minimum, maximum and step value. They will show up in each product edit page as the name of your custom Product Minimum followed by “Min”, “Max”, and “Step”. If you leave these fields blank, no limits will be applied unless you have enabled and set global values for that set of Product Minimums. Even if you do have the global values enabled, you can override the global values by entering a value in any of the minimums field (min, max, or step, in any combination — doesn’t have to be all or nothing).

If you have global values enabled and set for a set of Product Minimums, but you have a few products where you do NOT want to apply any of the limits, then you can enter default values into the fields for the individual products that will then override the global values and bypass any limits.  Use a value of 1 for the min and step values, and a value of 99999 for the max field to override the global maximum (99999 will be treated as no max limit, and will not be displayed as a max value if you are showing values in the shop or product pages).

Note that for Variable Products, the parent Variable product will have a set of Product Minimums fields on the general tab, and each variation will also have the same set of Product Minimums fields. Thus each variation can have its own min, max, and step values, which apply only to that variation. Any minimums fields you set for the parent variable product are checked against the sum total of all variations belonging to that parent variable product in the cart, and the user will not be able to checkout if those parent variable limits are not met.

Add To Cart functionality of Product Minimums

As long as your theme doesn’t modify the add-to-cart button arguments, WooCommerce User Role Minimums will adjust the quantity arguments for each product or variation based on the corresponding product minimums. The starting quantity will be set to the minimum quantity value, and the user will not be allowed to set it lower. The upper limit to the quantity input will be set by the maximum quantity value, or the current stock level (if smaller than the maximum quantity) if you are managing stock on a product level and back orders are not allowed. The quantity values will step up/down by the step value you enter, and values that are not a multiple of the step value will not be allowed.

Product quantities are also validated whenever a product is added to the cart, or if a quantity is updated in the cart. This is a double-check just in case the main add-to-cart quantity arguments are overridden by a theme (or other plugin), or if javascript is disabled in the customer’s browser, or the values are otherwise manipulated by the customer.

In addition, for simple products in the main shop loop, if they hit the “add-to-cart” button from any shop/category page, the quantity added to the cart will be the minimum quantity for that product.

Variable Product Minimums and Variations

As mentioned above, the parent variable product has its own Product Minimums fields, in addition to the same fields for every variation of that product. The way these sets of product minimums interact requires a bit more explanation. Often you will only use one set of the other, but they can be used in combination.

Product Minimums fields for each individual variation work the same way as already described above. When you select a variation, the min, max, and step arguments for the quantity input are adjusted according to the product minimums you set for that specific variation. Those will also be checked when the selected variation is added to the cart, or if you update the quantity for that variation in the cart.

The parent variable product minimums fields are validated on the cart and checkout pages only, and apply to the sum total quantity of all variations that belong to that parent variable product.

As an example, suppose you are selling a shirt that has 3 sizes and 3 colors, for a total of 9 possible variations. If you don’t care how many of each specific variation they order, but you want to make sure they order at least 3 shirts total (with each of the 3 shirts being any combination of size/color), then you only need to set the minimum quantity for the parent variable product. Same thing with the maximum if you want to limit the total number of shirts they can order. Note that there is no “step” value for the parent variable product minimums.

However, if you instead want to make sure that they order at least 3 shirts of a specific size/color combination, then you would enter those values in each specific variation’s product minimums fields where you want to apply min, max, and/or step quantity rules. In that case you may not need the parent variable product minimums.

If you set product minimums values both for variations and the parent variable product, then those are validated on an “AND” type of basis, meaning that the individual variation minimums must be met when adding/updating those variations individually, while the parent variable minimums are check against the sum total of all child variations before the user is allowed to checkout.

Version 1.1.0 – Options for when stock is below minimum quantity

In version 1.1.0 a check box option was added to allow the product (or variation) minimum to be ignored if the stock level is below the minimum quantity for the current user. This will only apply when you are managing stock for that product or variation, AND if you are NOT allowing backorders. If those conditions are met, and you have the option checked, then the minimum will be adjusted to the number of remaining stock.

If you do NOT check the new option (default is un-checked), then if the stock level is below the product/variation minimum for the current user, AND you are NOT allowing backorders, then the product will be set as non-purchasable. This will remove the add to cart button for the product or variation. A second option can be enabled to show a custom message on the product page for this particular situation. You can use this message to let the customer know why they can’t add the product or variation to their cart. There is a separate message shown for simple products and for product variations, since those must be hooked into different WooCommerce hooks to be displayed. Note that on simple products, if the product is not-purchasable, WooCommerce breaks out of their default templates before stock quantity is shown. However, for variable products, this is not the case since each variation can have its own stock level. Since this plugin allows you to set different minimums for each variation, the situation needs to be checked for each variation as the page is loaded and the message generated for each variation that meets the conditions. These messages are then show/hidden via javascript the same way that WooCommerce shows/hides the quantity inputs and add to cart buttons for each variation.

Category Quantity Minimums and Maximums

To set up category minimums and maximums, the first thing you must do is to create a new “set”. On the “Category Minimums” tab of the User Role Minimums page, enter a name (such as “wholesale”) for your set in the section labelled “Create a new set”, and click the “Add new Set” button.

After the page refreshes, you’ll see your new set name at the top with a big plus sign next to it. Click the plus sign for any set to expand it. You’ll then see two big boxes. On the left will be a list of all product categories and sub-categories from your WooCommerce setup. Click on the ones you want to create min/max quantities for, and then click on the double-arrows button to add those to the right side.  Once added, each category will have separate min and max quantity fields.  Enter the values you want (leave min or max blank for none). When you have them all set the way you want, make sure you hit the “Save Changes” button.  If you later need to delete any categories from your set, just use the “DELETE” button to remove it from the right side box, and then make sure to click on the “Save Changes” button again!

How Category Quantities are calculated

On the cart and the checkout pages, all items in the cart are checked to see if they belong to any categories that have min/max quantities set for the current customer. Products that are in a sub-category of a category for which there are minimums are also included.  The plugin counts the number of products in a category, including all of its sub-categories, to check against the min/max values, but makes sure that each product is counted only once for each category min/max. Since products can be included in multiple categories, we make sure that if you have it set, for example, in a parent category and one or more sub-categories, it only counts once against that parent category min/max.

In addition, sub-categories can be added to a set and have their own minimums, even if the parent category also has minimums. In that case, it would be treated as an “AND” type logic.

An example would be that you have a “clothing” parent category that you set a minimum quantity of 12.  You then have 3 sub-categories:  tops, bottoms, and accessories. You also add the “tops” category to your minimums set and set the min quantity to 2 for it. If the customer is buying anything from the clothing category, then they would need to have a minimum of 12 products, which can be any combination of quantities from those 3 sub-categories (or the parent category itself if there are some products that only belong to the parent category). If one of the products that the customer adds to the cart is in the “tops” sub-category, then they also must order at least 2 products from that category before they are allowed to checkout.

Please note that it is NOT required for the customer to buy anything from a category that has minimums set. As a further example, suppose your shop has the clothing set up as above, but also another category for “Shoes” that is NOT a sub-category of clothing, and does NOT have any minimums set. The customer could then order as many shoes as they want and check out without ordering anything from the “clothing” category.  In other words, category min/max values only apply when there is at least one item in the cart from the category (or a sub-category).

Category Amount Minimums and Maximums

These are setup exactly as described above for Category Quantity Minimums and Maximums, and work in exactly the same way except that the total currency amount is calculated for each category instead of the quantity of products in each category.

Order Quantity and Amount Minimums

Order quantity and order amount minimums are treated as separate minimums and can be enabled/disable separately, and mixed and matched for roles and individual users.

Version 2.1 adds a maximum value field to both the order quantity and order amount minimums sets. Note that with the inclusion of maximum values, you can leave one or the other blank (minimum or maximum), but at least one must be set in order to save your minimums “set”. Maximums are treated as hard limits and the customer will not be able to checkout if a maximum value is exceeded.

Similar to Product Minimums, be sure to enable one or both of the Order minimums on the plugin’s General Settings page. Order Quantity and Order Amount minimums each have their own tab, which work in basically the same way. Give your minimum a name, and enter desired values.  Once saved, the minimums will show in the list table at the top of the page. You can edit the values by typing over the existing value and pressing the Update/Delete button.

Once you create a minimums set, the name will appear as an option in the corresponding select box on the role settings page, as well on the edit user pages.

Note that you can use the same name for a product minimum, order quantity minimum, and order amount minimum. So, for example, if you have a set of all 3 minimums that you want to apply to wholesale customers only, you can name each one Wholesale.  But, you can also give them more generic names such as Level 1, Level 2, Level 3, etc., and then use any combination for roles or users. Use whatever naming convention that makes sense to you.

Order Quantity Minimums

This is a simple check of the total quantity of all products in the cart. If the minimum quantity is not met, or the maximum quantity is exceeded, the customer will not be able to checkout. Not much more too it than that. The order quantity must be a positive integer.

Order Amount Minimums

This is a simple check of the order grand total of all products in the cart. If the minimum amount is not met, or the maximum amount is exceeded, the customer will not be able to checkout. Not much more too it than that. The order amount must be formatted with only numbers and a decimal point (can leave out the decimal point if just using whole currency amount for minimum).

Version 1.3.0 adds an “Allow Free Orders” setting on the General Settings page. This is a global setting that you can check if you want to allow any customers to have free orders. When this box is checked, the order amount minimum (if it exists) for the current user will be ignored IF their order total is exactly zero.

Version 1.3 also adds compatibility with the WooCommerce Currency Converter extension, and will convert the order minimum amounts to the current selected currency of your customer. It will now also properly format the minimum amount when displayed in the cart message with the current currency symbol and settings. Make sure that you enter the minimum order amounts in your site’s default currency, and then it will use a function in the WooCommerce Currency Converter to convert to the selected currency as needed.

Multi-Currency Order Amounts

Version 1.6 adds a new Multi-Currency tab to the User Role Minimums setting page IF you have a multi-currency plugin active. The currently supported Multi-Currency plugins are the WPML/WCML Multi-Currency switcher, the Aelia Currency Switcher, and the WooCommerce Currency Converter (mentioned above). If any of those are active, the Multi-Currency tab will appear in the settings. For each active currency, you can set a manual minimum order amount if you want a nice rounded number for each currency minimum order amount. Otherwise, you can leave the fields blank to use the automatic currency conversion built in to any of the 3 supported multi-currency plugins.

Order Operator

The order operator only applies if you are using both order quantity and order amount minimums, and they are both set for a user or role. If those conditions apply, then choosing “AND” (the default) means that both the order quantity and order amount minimums must be met before the customer can checkout. Choosing “OR” means that they simply have to meet one of the minimums to be able to checkout. The order operator only applies to order minimums. Product Minimums conditions must always be met (when enabled and set).

Order Quantity Steps

Added in version 1.4.0, this new “minimums” field allows you to specify a step value, or multiple value, for the total quantity of all items in the cart. If the total quantity of all items in the cart is NOT a multiple of the assigned step value, the customer can not check out and an error message will be displayed. This is useful for when you want to only sell in quantities that fit nicely into a box or case for shipping, and you want to let them mix and match individual products of any quantity, as long as they order a quantity that is a multiple of the step value. Of course, you can still set any other minimums type as well, such as minimum order quantity or order amount, and/or individual product min, max, or step values.

Min, Max, and Step Qty display options

Customers may get confused about why they are not allowed to order certain quantities of products, especially if you have different minimums, maximums, and/or step values for different products and variations. There are several options for displaying the min/max qty values in the shop pages as well as the individual product pages. Min Qty, Max Qty, and Step Qty displays in the shop loop can be enabled/disabled separately on the main General Settings page of the plugin options.

In the “Messages” section of the General Settings page, you can specify the text for the Min Qty, Max Qty, and Step Qty display, along with a placeholder to specify where you want the numeric amount to appear. If you set any of those to blank, then it will not show in either the shop loop or the individual product pages. If you only want to show them on the individual product pages, then set your text for each in the Messages section, but disable them on the shop page by unchecking the options on the main General Settings page.

For Variable Products, you can also specify a heading for the main variable product min and max quantities, as well as a heading for the variation min/max/step quantities. These headings will appear above the Min Qty and Max Qty text, and is useful if you are using both Variable minimums along with individual variation minimums, so your customers understand which is which. Set either (or both) of those headings blank to hide the headings.

Error Messages

The rest of the Messages you can define in the messages section are for all the various minimums errors that can occur. There is a description next to each message field, and the default values should also help to figure out which message appears when. Note the placeholders for showing the quantity, step, and product title.

Shop/Category Notices

Version 1.6 adds a new section to the General settings tab that allows you to define custom messages for shop and/or category pages, where you can notify customers of any minimums that might apply to them (so they aren’t surprised by the error messages on the cart or checkout pages).

The Shop Notice appears on any regular WooCommerce shop pages, which are determined by the conditional is_shop() WooCommerce function. This notice will ONLY appear if the current customer has any minimums that apply to them.

The Category Notice message appears only on product category archives, which are determined by the condition is_product_category() function of WooCommerce. This notice will ONLY appear for categories that have a minimums set that is active for the current user.

The Category Loop message is the message you should use to describe any category minimums for the current user, and the text you enter there will be repeated for every category minimum that applies to the current customer. You include the Category Loop message into either (or both) of the other messages (Shop or Category) by using the {category_loop} tag.

Message template tags are placeholders in your message that will be replaced by the corresponding values of the minimums that apply to the current customer. If any of those values are NOT set for the current customer’s minimums, then it will be replaced instead by the “No value text” that you enter at the bottom.

HTML is allowed in the messages, so you can format the text the way you want, or add CSS classes or ids as necessary to style the notices the way you want. The messages are put into a div with the “woocommerce-notice” class, so they will have the styling of the regular WooCommerce notices as set by either WooCommerce or your theme. However, those divs also have a class of “urm-shop-notice” added, so you can more easily target the entire notice div for custom CSS or javascript. The class is the same for both shop and category notices.