Basket Validators (Checkout Validation)

The BASKET_VALIDATORS setting defines validation rules applied before checkout. These validators ensure basket contents meet business requirements before order creation.

Validator Structure:

{
  "condition_klass": "path.to.ValidatorClass",
  "kwargs": {
    "param1": "value1",
    "param2": "value2"
  },
  "message": {
    "en": "Error message in English",
    "tr": "Türkçe hata mesajı"
  }
}

Available Validators:

1. BasketItemQuantityValidator

• Validates total quantity of items with specific attribute value

• Parameters:

  • attribute_name: Product attribute to check

  • attribute_value: Value to match

  • upper_limit: Maximum allowed quantity

  • lower_limit: Minimum allowed quantity

• Use Case: Limit promotional items or restrict bulk purchases by category

• Configuration Example:

  {
    "condition_klass": "omnishop.baskets.validator.BasketItemQuantityValidator",
    "kwargs": {
      "attribute_name": "promotion_category",
      "attribute_value": "black_friday_deal",
      "upper_limit": 5,
      "lower_limit": 1
    },
    "message": {
      "en": "You can only add between 1 and 5 Black Friday deal items per order",
      "tr": "Sipariş başına sadece 1 ile 5 arasında Black Friday ürünü ekleyebilirsiniz"
    }
  }

• Product Example: Products tagged with promotion_category: "black_friday_deal" limited to 5 total units

2. BasketItemBaseCodeQuantityValidator

• Validates quantity per product base code

• Parameters: Same as BasketItemQuantityValidator

• Checks each unique base code separately (prevents buying same product in different variants)

• Use Case: Limit purchases per product family regardless of size/color variants

• Configuration Example:

  {
    "condition_klass": "omnishop.baskets.validator.BasketItemBaseCodeQuantityValidator",
    "kwargs": {
      "attribute_name": "limited_edition",
      "attribute_value": true,
      "upper_limit": 2,
      "lower_limit": 1
    },
    "message": {
      "en": "Limited edition item {base_code}: Maximum 2 units per product family allowed",
      "tr": "Sınırlı sayıda ürün {base_code}: Ürün ailesi başına maksimum 2 adet"
    }
  }

• Product Example: Shirt with base_code "SHIRT-001" (variants: SHIRT-001-S-RED, SHIRT-001-M-BLUE) limited to 2 total across all variants

3. BasketItemSteppedQuantityValidator

• Enforces quantity steps (multiples) with min/max bounds

• Parameters:

  • attribute_name: Attribute containing step value (from product)

  • upper_limit_attribute_name: Attribute for max quantity (from product)

  • lower_limit_attribute_name: Attribute for min quantity (from product)

• Use Case: Bulk-only products (wholesale, packaging constraints)

• Configuration Example:

  {
    "condition_klass": "omnishop.baskets.validator.BasketItemSteppedQuantityValidator",
    "kwargs": {
      "attribute_name": "order_step",
      "upper_limit_attribute_name": "max_order_quantity",
      "lower_limit_attribute_name": "min_order_quantity"
    },
    "message": {
      "en": "Quantity must be multiple of {step} and between {lower_limit} and {upper_limit}",
      "tr": "Miktar {step}'in katı olmalı ve {lower_limit} ile {upper_limit} arasında olmalıdır"
    }
  }

• Product Example:

  • Product attributes: order_step: 6, min_order_quantity: 12, max_order_quantity: 60

  • Valid quantities: 12, 18, 24, 30, 36, 42, 48, 54, 60

  • Invalid quantities: 10, 15, 70 (not multiples of 6 or outside bounds)

4. AttributeValidator

• Validates product attribute has expected value

• Parameters:

  • attribute_name: Attribute to check

  • expected_value: Required value

  • disabled_on_sub_basket_items: Skip sub-items (default: false)

• Use Case: Ensure all basket items meet specific criteria (shipping, region, etc.)

• Configuration Example 1 - Shipping Validation:

  {
    "condition_klass": "omnishop.baskets.validator.AttributeValidator",
    "kwargs": {
      "attribute_name": "international_shipping",
      "expected_value": "true",
      "disabled_on_sub_basket_items": false
    },
    "message": {
      "en": "Some items cannot be shipped internationally. Attribute {attribute_name} must be {expected_value} but found {attribute_value}",
      "tr": "Bazı ürünler uluslararası gönderilememektedir"
    }
  }

• Configuration Example 2 - Region Lock:

  {
    "condition_klass": "omnishop.baskets.validator.AttributeValidator",
    "kwargs": {
      "attribute_name": "available_region",
      "expected_value": "EU",
      "disabled_on_sub_basket_items": true
    },
    "message": {
      "en": "Product not available in your region",
      "tr": "Ürün bölgenizde mevcut değil"
    }
  }

5. SingleDataSourceValidator

• Ensures all basket items from same seller (marketplace)

• No parameters required

• Prevents mixing products from different sellers in single order

• Critical for marketplace multi-vendor scenarios

• Use Case: Enforce single-seller per order policy in marketplace

• Configuration Example:

  {
    "condition_klass": "omnishop.baskets.validator.SingleDataSourceValidator",
    "kwargs": {},
    "message": {
      "en": "Your cart cannot contain products from different sellers. If you wish to add this product, please empty your cart.",
      "tr": "Sepetiniz farklı satıcılardan ürün içeremez. Bu ürünü eklemek için lütfen sepetinizi boşaltın."
    }
  }

• Behavior: If basket has items from Seller A, cannot add items from Seller B

Validation Timing:

• Validators run before checkout/order creation

• Errors block order submission

• Messages support internationalization

• Failed validations return all error messages