Basket Validators
Basket validators are used to enforce business rules on basket items. They are configured via the BASKET_VALIDATORS dynamic setting and are executed automatically whenever items are added to the basket.
These validations help prevent invalid orders and ensure that business constraints are consistently applied before checkout.
1. Overview
Key Characteristics:
Validators run automatically after items are added to the basket
Multiple validators can be configured and executed together
Each validator supports localized error messages
Validation errors are returned in the API response and block checkout
2. Configuration Structure
Each entry in the BASKET_VALIDATORS setting follows the structure below:
{
"condition_klass": "omnishop.baskets.validator.ValidatorClassName",
"kwargs": {
"param1": "value1",
"param2": "value2"
},
"message": {
"en-us": "English error message",
"tr-tr": "Turkish error message"
}
}condition_klass
string
Validator identifier (see available validators below)
kwargs
dict
Parameters specific to the validator
message
dict
Localized error messages keyed by locale code (e.g., en-us, tr-tr)
If no message is defined for the current language, the validator’s default message is used.
3. Available Validators
3.1. Basket Item Quantity Validator
Validates the total quantity of basket items that share a specific attribute value. An error is triggered when the total quantity falls within a restricted range.
Parameters:
attribute_name
string
Product attribute key to check
attribute_value
string
Value to match
upper_limit
int
Upper bound of the restricted range
lower_limit
int
Lower bound of the restricted range
Behavior:
Sums quantities of all basket items matching the given attribute
Fails when
lower_limit <= total_quantity < upper_limitPasses when
total_quantity < lower_limitortotal_quantity >= upper_limit
Understanding the Logic:
With lower_limit=1, upper_limit=3 (meaning: "if the product is purchased, at least 3 units must be bought"):
0
Not purchased
✅ PASS
1
Buying, but below minimum
❌ FAIL
2
Buying, but below minimum
❌ FAIL
3
Meets minimum
✅ PASS
4+
Above minimum
✅ PASS
This validator enforces a “buy at least X or don’t buy at all” rule, which is common for wholesale or bulk products.
Example 1 - B2B Wholesale: Minimum order quantity
For B2B customers, require at least 10 wholesale units in total:
No wholesale items
0
✅ PASS
3x Product A (wholesale)
3
❌ FAIL
5x Product A + 5x Product B (both wholesale)
10
✅ PASS
12x Product A (wholesale)
12
✅ PASS
This validator counts the total quantity across all products with the matching attribute, not per individual SKU.
Example 2 - Promotional Campaign: Block out-of-campaign items
During a special campaign, block items not included in the promotion:
0 items
✅ PASS
1+ items
❌ FAIL
Example 3 - Alcohol Regulation: Age-restricted products
Block alcohol products in regions where online alcohol sales are prohibited:
3.2. Basket Item Base Code Quantity Validator
Similar to BasketItemQuantityValidator, but validates quantity limits per product variant group (base_code). This is ideal for flash sales and limited-edition products.
Parameters:
attribute_name
string
Product attribute key to check
attribute_value
string
Value to match
upper_limit
int
Upper bound per base_code
lower_limit
int
Lower bound per base_code
Behavior:
Groups basket items by base_code (e.g., same product in different sizes/colors)
Triggers error when
lower_limit <= quantity < upper_limitfor any base_code
Example 1 - Flash Sale: Max 2 per product (all sizes/colors combined)
During a flash sale, limit customers to 2 units total per product (base_code), regardless of which size/color they choose:
Scenario: T-shirt (base_code: TSHIRT-001) available in S, M, L sizes
1x Small
1
✅ PASS
1x Small + 1x Medium
2
✅ PASS
2x Small + 1x Medium
3
❌ FAIL
3x Small
3
❌ FAIL
This validator counts all variants (sizes/colors) under the same base_code together, not per individual SKU.
Example 2 - Limited Edition Sneakers: Max 1 per model
For limited edition sneakers, allow only 1 unit per model (base_code), regardless of size:
Scenario: Sneaker model (base_code: SNKR-AIR-001) available in sizes 40, 41, 42
1x Size 42
1
✅ PASS
1x Size 42 + 1x Size 43
2
❌ FAIL
The error message supports {} placeholder which will be replaced with the base_code.
3.3. Basket Item Stepped Quantity Validator
Ensures that quantities are multiples of a step value and fall within defined minimum and maximum limits. All values are read from product attributes.
This validator is commonly used for grocery and bulk products.
Parameters:
attribute_name
string
Attribute holding the step value
upper_limit_attribute_name
string
Attribute holding the maximum quantity
lower_limit_attribute_name
string
Attribute holding the minimum quantity
Behavior:
Reads step, minimum, and maximum from product attributes
Triggers error if quantity is not a multiple of step or outside min/max range
Products without the required attributes are skipped
Example 1 - Grocery Store: Eggs sold in packs of 6
Eggs can only be purchased in multiples of 6 (half dozen), minimum 6, maximum 30:
Product Attributes for Eggs:
3
❌ FAIL (not multiple of 6)
6
✅ PASS
7
❌ FAIL (not multiple of 6)
12
✅ PASS
36
❌ FAIL (exceeds max 30)
Example 2 - Bulk Store: Water bottles sold in cases
Water bottles sold in cases of 12, minimum 12, maximum 96:
Product Attributes for Water Bottles:
Example 3 - Wholesale: Bulk flour by 5kg bags
Flour sold in 5kg increments, minimum 10kg, maximum 100kg:
Product Attributes for Bulk Flour:
3.4. Attribute Validator
Validates that product attribute matches an expected values. This validator is useful for enforcing conditional business rules.
Parameters:
attribute_name
string
Product attribute to check
expected_value
string
Expected value for the attribute
disabled_on_sub_basket_items
bool
If true, skip validation for sub-items (bundle components)
Behavior:
Products without the attribute pass validation(skipped)
Products with matching attribute value pass
Products with different attribute value fail
Example 1 - Miscellaneous Products: Block standalone purchase
Accessories and add-on items (gift wrapping, extended warranty, installation service) that can only be purchased with a main product:
No cannot_be_sold_alone attribute
✅ PASS (regular product)
cannot_be_sold_alone: "false"
✅ PASS
cannot_be_sold_alone: "true"
❌ FAIL (addon without main product)
Set disabled_on_sub_basket_items: true to allow these items as bundle components while blocking standalone purchase.
Example 2 - Pre-order Products: Block if not accepting pre-orders
Block pre-order items when pre-order period has ended:
Example 3 - Subscription Products: Require active subscription
Block subscription-only products for non-subscribers:
3.5. Single Data Source Validator
Ensures all basket items are from the same seller/data source. Essential for marketplace platforms with single-seller checkout.
Parameters: None required (empty kwargs: {})
Behavior:
Triggers error if basket contains items from different sellers
Empty baskets pass validation
Use Case - Marketplace Single-Seller Checkout:
Many marketplaces require orders to be fulfilled by a single seller for:
Simplified logistics and shipping
Consistent delivery experience
Easier returns and customer service
Scenario:
Customer adds Product A from Seller X → ✅ PASS
Customer adds Product B from Seller X → ✅ PASS (same seller)
Customer adds Product C from Seller Y → ❌ FAIL (different seller)
4. Default Error Messages
Each validator has a built-in default error message used when no localized message is configured:
BasketItemQuantityValidator
"Product quantity exceeded"
BasketItemBaseCodeQuantityValidator
"Base code {} quantity exceeded"
BasketItemSteppedQuantityValidator
"Quantity must be multiple of {step} and between {lower_limit} and {upper_limit}"
AttributeValidator
"{attribute_name} must be {expected_value} but it is {attribute_value}"
SingleDataSourceValidator
"Your cart cannot contain products from different sellers. If you wish to add this product, please empty your cart."
Last updated
Was this helpful?