Setting a maximum order quantity based on user roles in WooCommerce can be useful for wholesale stores, membership sites, and B2B eCommerce. For example, you might want retail customers to buy no more than 5 items per order, but allow wholesale customers to purchase up to 100 items.
In this guide, we’ll show you how to set the maximum order quantity for each user role in WooCommerce — without using a plugin.
Step 1: Define Maximum Order Quantity for Each User Role
To set different maximum order quantities for each user role, we first define the user roles and the limits for each role.
Code to Define Maximum Order Quantities
Add this code to your theme’s functions.php file or a child theme:
/*
* Snippet: How to Set Maximum Order Quantity Based on User Role in WooCommerce – 2026
* Author: John Cook
* URL: https://wcsuccessacademy.com/?p=1785
* Tested with WooCommerce 10.7.0
* "This function sets the maximum order quantity for each user role"
*/
function wcsuccess_get_maximum_order_quantity_by_role() {
return array(
'customer' => 5, // Retail customers can only order 5 items per order
'subscriber' => 10, // Subscribers can order up to 10 items per order
'wholesale_customer' => 100, // Wholesale customers can order up to 100 items per order
);
}
Explanation:
- Role Definitions: Sets maximum order limits for each user role (e.g., customer, subscriber, wholesale_customer).
- Customisation: Change the role names and limits as needed.
Step 2: Restrict Cart Quantity Based on User Role
Once the maximum order limits are defined, we apply the restriction to the cart using WooCommerce hooks.
Code to Restrict Cart Quantity Based on User Role
Add this code to your functions.php file:
/*
* Snippet: How to Set Maximum Order Quantity Based on User Role in WooCommerce – 2026
* Author: John Cook
* URL: https://wcsuccessacademy.com/?p=1785
* Tested with WooCommerce 10.7.0
* "This function restricts the maximum order quantity based on the user role"
*/
function wcsuccess_restrict_cart_quantity_by_role() {
if ( is_admin() && ! defined( 'DOING_AJAX' ) ) {
return;
}
// Get the current user's role
$user = wp_get_current_user();
$user_roles = (array) $user->roles;
$current_role = isset( $user_roles[0] ) ? $user_roles[0] : 'guest';
// Get maximum order quantities by role
$role_quantities = wcsuccess_get_maximum_order_quantity_by_role();
$max_quantity = isset( $role_quantities[ $current_role ] ) ? $role_quantities[ $current_role ] : 0;
if ( $max_quantity > 0 ) {
$total_quantity = WC()->cart->get_cart_contents_count();
if ( $total_quantity > $max_quantity ) {
wc_add_notice( sprintf(
__( 'You can only purchase a maximum of %d items as a %s.', 'woocommerce' ),
$max_quantity,
$current_role
), 'error' );
// Remove excess items from the cart
foreach ( WC()->cart->get_cart() as $cart_item_key => $cart_item ) {
WC()->cart->remove_cart_item( $cart_item_key );
}
}
}
}
add_action( 'woocommerce_before_checkout_process', 'wcsuccess_restrict_cart_quantity_by_role' );
Explanation:
- Role Check: Identifies the user’s role and retrieves the appropriate maximum order quantity.
- Quantity Restriction: Checks the total number of items in the cart. If the quantity exceeds the limit, WooCommerce displays an error message and prevents checkout.
- Automatic Cart Adjustment: If the cart exceeds the quantity limit, the script removes the excess items and notifies the customer.
Step 3: Prevent Customers from Adding More Than the Maximum Quantity
While the above code prevents checkout, it’s better to stop users from adding too many items to the cart in the first place.
Code to Prevent Adding More Than the Maximum Quantity
Add this code to your functions.php file:
/*
* Snippet: How to Set Maximum Order Quantity Based on User Role in WooCommerce – 2026
* Author: John Cook
* URL: https://wcsuccessacademy.com/?p=1785
* Tested with WooCommerce 10.7.0
* "This function prevents users from adding more items than their role allows"
*/
function wcsuccess_limit_cart_quantity_on_add( $passed, $product_id, $quantity, $variation_id = '', $variations = '', $cart_item_data = array() ) {
$user = wp_get_current_user();
$user_roles = (array) $user->roles;
$current_role = isset( $user_roles[0] ) ? $user_roles[0] : 'guest';
$role_quantities = wcsuccess_get_maximum_order_quantity_by_role();
$max_quantity = isset( $role_quantities[ $current_role ] ) ? $role_quantities[ $current_role ] : 0;
if ( $max_quantity > 0 ) {
$total_quantity_in_cart = WC()->cart->get_cart_contents_count();
$new_total_quantity = $total_quantity_in_cart + $quantity;
if ( $new_total_quantity > $max_quantity ) {
wc_add_notice( sprintf(
__( 'You can only purchase up to %d items as a %s.', 'woocommerce' ),
$max_quantity,
$current_role
), 'error' );
return false; // Prevent adding more items
}
}
return $passed;
}
add_filter( 'woocommerce_add_to_cart_validation', 'wcsuccess_limit_cart_quantity_on_add', 10, 6 );
Explanation:
- Prevention: Stops users from adding more items to the cart if the total quantity will exceed the limit.
- Custom Error Message: Provides users with feedback so they understand why the item wasn’t added to the cart.
Customisation Options
Customise User Roles
If your store uses custom roles (like wholesale_customer), you can add these roles to the $role_quantities array:
return array(
'customer' => 5,
'subscriber' => 10,
'wholesale_customer' => 100,
'premium_member' => 50, // Example of a custom role
);
Example Workflow
- Customer Role (Retail User)
- Maximum Order Quantity: 5
- If they try to add 6 items to the cart, they’ll see: “You can only purchase a maximum of 5 items as a customer.”
- Wholesale Customer Role
- Maximum Order Quantity: 100
- If they add 101 items to the cart, they’ll see: “You can only purchase a maximum of 100 items as a wholesale customer.”
- Subscriber Role
- Maximum Order Quantity: 10
- If they try to add 12 items to the cart, they’ll see: “You can only purchase a maximum of 10 items as a subscriber.”
Example Use Case
| User Role | Maximum Quantity |
|---|---|
| Customer | 5 items |
| Subscriber | 10 items |
| Wholesale Customer | 100 items |
| Guest | 0 items (Customise) |
Note: Guest users are treated as a “role” (
guest) and can be given a maximum order quantity like any other role.
Use Cases
- Wholesale Restrictions: Prevent wholesale customers from buying more than 100 units at a time.
- Guest Limits: Stop guest users from purchasing more than 3 items at a time to encourage registration.
- Retail vs Wholesale: Allow retail customers to buy only 5 items, but wholesale users can buy up to 100.
Conclusion
Setting a maximum order quantity by user role in WooCommerce is a great way to control customer purchasing behaviour. By following this guide, you can set different quantity limits for retail customers, subscribers, and wholesale users. This approach is ideal for stores that want to offer exclusive purchase limits for certain roles or memberships.
Test these changes in a staging environment before applying them to your live site. For more WooCommerce customisation options, check out our WooCommerce Visual Hooks Guide or use our wp-config generator for advanced configurations.
I have been working with WordPress and WooCommerce since 2012 and have developed a deep knowledge of the content management system. Since 2012, I have developed several plugins and designed dozens of websites utilising different frameworks, CMS’s and programming languages. I am proficient in PHP, Python, Java, C, C++, R and JavaScript with limited experience in Go, Kotlin and Swift.
Educationally, I have a Master’s degree in cyber security a Bachelor’s (Hons, First Class) in Applied Research and a Graduate Certificate in Data Science. I’m currently undertaking PhD studies investigating IoT cybersecurity. I recently graduated with First Class Honours and Masters of Information Technology, receiving the Executive Dean’s Award for studies undertaken in the 2021 and 2022 academic years. I have worked in the information technology industry for the past 11 years primarily as a software/web developer specific to design, optimisation, network management and security. My research interests are in the areas of Internet of Things (IoT), 5G and Beyond Networks, information security for wireless networks and software development.
Stay In Touch
