Docs Portal

Configuration-Based Behavior

The Basket API behavior can be customized through various system settings. Below is a comprehensive list of all settings with their configuration methods:

Settings Configuration Methods

Dynamic Settings (Runtime Configurable via Admin Panel): These settings are registered with dj_dynamic_settings and can be modified at runtime through the admin interface without code deployment:

From omnishop.baskets.settings.conf:

  • ✅ BASKET_MAX_ITEM_COUNT - Can also be set via ENV or directly in settings.py

  • ✅ BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB - Dynamic setting only

  • ✅ IS_SUB_BASKET_ITEM_QUANTITY_SAME_AS_PARENT - Can also be set via ENV or directly in settings.py

  • ✅ BASKET_VALIDATORS - Can also be set via ENV or directly in settings.py

  • ✅ BASKET_ITEM_REMOTE_PRICE_CLIENT_CONF - Dynamic setting only

  • ✅ BASKET_SERVICE_CONDITIONS - Can also be set via ENV or directly in settings.py

  • ✅ BASKET_PRODUCT_MAX_QUANTITY_ATTRIBUTE - Can also be set via ENV or directly in settings.py

  • ✅ BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE - Can also be set via ENV or directly in settings.py

  • ✅ BASKET_NAMESPACE_VALIDATORS - Can also be set via ENV or directly in settings.py

  • ✅ RESET_BASKET_ON_SEGMENT_CHANGE - Can also be set via ENV or directly in settings.py

From omnishop.products.settings.conf:

  • ✅ IS_MARKETPLACE - Can also be set via ENV or directly in settings.py

  • ✅ OFFER_MISCELLANEOUS_ATTRIBUTE_KEY - Can also be set via ENV or directly in settings.py

  • ✅ REMOTE_PRICE_ATTRIBUTE_KEY - Can also be set via ENV or directly in settings.py

Weight-Based Product Sales Settings: These settings can also be configured via environment variables:

  • 🔧 BASKET_UNIT_VALUE_ATTRIBUTE - ENV: BASKET_UNIT_VALUE_ATTRIBUTE (default: 'basket_unit_value')

  • 🔧 UNIT_STEP_VALUE_ATTRIBUTE - ENV: UNIT_STEP_VALUE_ATTRIBUTE (default: 'unit_step_value')

  • 🔧 UNIT_REFERENCE_VALUE_ATTRIBUTE - ENV: UNIT_REFERENCE_VALUE_ATTRIBUTE (default: 'unit_reference_value')

  • 🔧 UNIT_PRODUCT_FLAG_ATTRIBUTE - ENV: UNIT_PRODUCT_FLAG_ATTRIBUTE (default: 'is_unit_product')

  • 🔧 UNIT_MINIMUM_VALUE_ATTRIBUTE - ENV: UNIT_MINIMUM_VALUE_ATTRIBUTE (default: 'unit_minimum_value')

  • Detailed Documentation: https://docs.akinon.com/technical-guides/commerce/weight-based-product-sales

Core Settings

IS_MARKETPLACE (boolean, default: false):

  • When enabled, datasource field becomes required for all basket operations

  • Products must be associated with a specific seller/datasource

  • Extra product pricing and stock information is included in responses

  • Enables multi-seller marketplace functionality

BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB (integer, default: 0):

  • Controls maximum size of custom attributes per basket item in kilobytes

  • Default 0 means no limit, typical value is 10KB

  • Prevents oversized data in gift notes, form fields, etc.

  • Returns validation error if limit exceeded

OFFER_MISCELLANEOUS_ATTRIBUTE_KEY (string, default: "cannot_be_sold_alone"):

  • Determines which offer products can be added as miscellaneous sub-items

  • Controls validation of sub-items in basket operations

  • Used to identify promotional miscellaneous products

Basket Quantity Limits

BASKET_MAX_ITEM_COUNT (integer, default: 80):

  • Total quantity limit of all items in the cart

  • Prevents baskets from becoming too large

  • Checked when adding/updating items

BASKET_PRODUCT_MAX_QUANTITY_ATTRIBUTE (string, default: ""):

  • Product attribute key that defines maximum quantity per product

  • Applied globally across all users

  • Example: Product with max_quantity: 10 cannot exceed 10 units in basket

BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE (string, default: ""):

  • Product attribute key for maximum quantity per user within time window

  • Combined with BASKET_PRODUCT_USER_MAX_QUANTITY_GAP_HOUR (default: 24h)

  • Includes both basket and recent orders in calculation

  • Prevents single user from purchasing excessive quantities

Sub-Item Behavior

IS_SUB_BASKET_ITEM_QUANTITY_SAME_AS_PARENT (boolean, default: false):

  • When true, sub-product quantities automatically match parent product quantity

  • Affects extra products and miscellaneous items

  • When false, sub-items maintain independent quantities

Basket Validators

BASKET_VALIDATORS (list of validator configurations, default: []):

  • Custom validation rules applied to basket before checkout

  • Each validator has: condition_klass, kwargs, message (multi-language)

  • Available validators:

    • BasketItemQuantityValidator: Validates quantity based on product attributes

    • BasketItemBaseCodeQuantityValidator: Validates quantity by product base code based on product attributes

    • BasketItemSteppedQuantityValidator: Enforces quantity steps (e.g., multiples of 6)

    • AttributeValidator: Validates product attribute values

    • SingleDataSourceValidator: Ensures all items from same seller (marketplace)

  • Errors returned during checkout validation

Service Conditions

BASKET_SERVICE_CONDITIONS (list of condition paths, default: []):

  • Conditions checked when basket items are added/modified (runtime validation)

  • Applied during POST/PUT operations, not during checkout

  • Available conditions with detailed configuration examples:

1. basket_user_max_quantity

  • Purpose: Enforces per-user quantity limits over configurable time periods

  • Module: omnishop.baskets.conditions.basket_user_max_quantity

  • Parameters: Requires product attributes:

    • max_user_quantity: Maximum quantity user can order

      • Attribute name need to be set via BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE

  • Use Case: Limit purchases per user to prevent abuse/scalping

  • Configuration Example:

    BASKET_SERVICE_CONDITIONS = [
    "omnishop.baskets.conditions.basket_user_max_quantity"
]

  • Product Attributes Example:

    {
  "max_user_quantity": 2
}

  • Behavior:

    • Queries user's order history for last N days

      • N is configurable via BASKET_PRODUCT_USER_MAX_QUANTITY_GAP_HOUR (default: 24 hours)

    • Sums quantities of same product

    • Rejects if adding current quantity exceeds limit

    • Example: User can only buy 2 units in 30 days

2. basket_item_max_count

  • Purpose: Enforces maximum total item count in basket

  • Module: omnishop.baskets.conditions.basket_item_max_count

  • Use Case: Simplify order processing, limit basket items

  • Configuration Example:

    BASKET_SERVICE_CONDITIONS = [
    "omnishop.baskets.conditions.basket_item_max_count"
]

  • Behavior:

    • Counts basket items in quantity

    • Compares against BASKET_MAX_ITEM_COUNT setting

    • Prevents adding new item if count exceeds max item count setting

    • Error: "Maximum of {max item count} items can be added to the cart."

3. bundle_type_compatibility_condition

  • Purpose: Validates bundle type compatibility between products

  • Module: omnishop.baskets.conditions.bundle_type_compatibility_condition

  • Parameters: Requires BUNDLE_TYPE_CONFIGURATION static setting (configured in settings.py)

  • Use Case: Prevent incompatible product bundles (e.g., subscription + one-time)

  • Configuration Example:

    BASKET_SERVICE_CONDITIONS = [
    "omnishop.baskets.conditions.bundle_type_compatibility_condition"
]

BUNDLE_TYPE_CONFIGURATION = {
    "INCOMPATIBLE_BUNDLE_TYPES": (
        ("subscription", "one_time_purchase"),
        ("recurring_payment", "prepaid")
    ),
    "ATTRIBUTE_NAME": "bundle_type"
}

  • Product Attributes Example:

    {
  "bundle_type": "subscription"
}

  • Behavior:

    • Reads bundle_type attribute from products

    • Checks against INCOMPATIBLE_BUNDLE_TYPES configuration

    • Prevents adding product if bundle type conflicts with existing items

    • Error: "This product cannot be purchased with the other products in the basket. If you add this product to the basket, other product(s) will be removed."

    • Example: Cannot mix "subscription" and "one_time_purchase" products

4. extra_product_quantity_condition

  • Purpose: Prevents quantity changes for basket items that have extra products/sub-items attached

  • Module: omnishop.baskets.conditions.extra_product_quantity_condition

  • Parameters: None (automatic detection of items with sub-items)

  • Use Case: Protect parent-child relationships (warranties, gift wrapping, accessories, etc.)

  • Configuration Example:

    BASKET_SERVICE_CONDITIONS = [
    "omnishop.baskets.conditions.extra_product_quantity_condition"
]

  • Behavior:

    • Detects if basket item has sub-items (extra products) attached to it

    • Prevents direct quantity modification of the parent item when sub-items exist

    • User must remove sub-items first, then modify parent quantity

    • Error: "The orders related to miscellaneous product do not accept changing quantity"

  • Example:

    • User adds Laptop (qty: 1)

    • User adds Extended Warranty as extra product (attached to laptop as sub-item)

    • User tries to change Laptop quantity from 1 to 2 → BLOCKED

    • User must first remove the warranty, then change laptop quantity, then re-add warranty if desired

Namespace Settings

BASKET_NAMESPACE_VALIDATORS (list of validator configurations, default: see below):

  • Validators for namespace-based basket operations

  • Default validators:

    • NullNamespaceValidator: Prevents namespace from being None

    • ActiveBasketCountValidator: Limits number of active baskets (default: 5)

    • NamespaceDataSourceValidator: Validates namespace matches datasource

    • DefaultNamespaceValidator: Prevents namespace string "null"

  • Each validator can have custom kwargs for configuration

RESET_BASKET_ON_SEGMENT_CHANGE (boolean, default: true):

  • When true, basket is cleared when user segment changes

  • Segment changes affect pricing/stock lists

  • Prevents price inconsistencies across segments

Remote Pricing

BASKET_ITEM_REMOTE_PRICE_CLIENT_CONF (dict, default: {"headers": {"Authorization": "Bearer test_token"}, "url": "http://localhost:8000/"}):

  • Configuration for remote price calculation service

  • Contains url and headers for remote API

  • Used when pricing comes from external systems

  • Detailed Documentation: https://docs.akinon.com/technical-guides/commerce/remote-price

PreviousSpecial FeaturesNextUnavailable Product Scenarios

Was this helpful?