> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/basket/introduction/basket-validators-checkout-validation.md).

# 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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/basket/introduction/basket-validators-checkout-validation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.