Installment Filters

The installment filtering feature allows users to determine the most suitable installment options based on the products in their basket and the available payment methods. This feature operates within a set of rules and criteria to provide users with dynamic and customized payment solutions. The filtering process is designed to optimize installment options according to product categories, prices, payment methods, attributes, and other conditions.

Filter Types and Descriptions

The filters used in installment filtering are listed below.

Class	Label	Description
omnishop.payments.filters.CategoryInstallmentFilter	Category Installment Filter	Limits installments based on product categories. For example, electronic products may have a maximum of 6 installments.
omnishop.payments.filters.CategorySpecialInstallmentFilter	Category Special Installment Filter	Offers special installment options within specific categories or higher hierarchies, and within certain price ranges. For example, furniture over 10,000 ₺ may have up to 12 installments.
omnishop.payments.filters.CommerceCardInstallmentFilter	Commerce Card Installment Filter	Filters installment options that are only valid for commercial cards. When a user uses a commercial card, it becomes active and overrides other filters, showing only installment options applicable to commercial cards.
omnishop.payments.filters.CategorySpecialInstallmentCommerceCardFilter	Category Special Installment Commerce Card Filter	Provides category-based special installment limitations for commercial cards. For example, a maximum of 6 installments for white goods when using a commercial card.
omnishop.payments.filters.ProductInstallmentFilter	Product Installment Filter	Limits installments based on specific product attributes. For example, discounted products may not be eligible for installments.
omnishop.payments.filters.AttributeFilter	Attribute Filter	Restricts installment options based on a specific attribute value of a product in the basket, while allowing certain values to be excluded from this restriction.
omnishop.payments.filters.BasketAmountFilter	Basket Amount Filter	Limits installment options according to the total basket amount. For example, installments may not be available for purchases under 500 ₺.
omnishop.payments.filters.AttributeSetFilter	Attribute Set Filter	Configures installment options based on products with a specific attribute set. For example, a maximum of 3 installments for products with a “premium” feature.
omnishop.payments.filters.DuplicateInstallmentFilter	Duplicate Installment Filter	Matches installment options based on specific attribute values of products in the basket and provides suitable installment options based on these matches.
omnishop.payments.filters.CurrencyInstallmentFilter	Currency Installment Filter	Limits installments according to the currency used in the basket. For example, installments may only be available for transactions in TRY.
omnishop.payments.filters.EmailInstallmentFilter	Email Domain Installment Filter	Limits available installment options based on the user's email domain and a specified comparison operator. For example, users with an akinon.com email may only see installments less than or equal to 3.
omnishop.payments.filters.EmailSelectInstallmentFilter	Email Domain Select Installment Filter	Applies installment filtering rules based on email verification status and/or email domain. For example, only verified akinon.com users may access certain installment options.

Configuring Installment Filters with Dynamic Setting

Installment filters are configured through Dynamic Settings. Follow the steps below to set them up:

1. Navigate to Omnitron > Sales Channels > Sales Channel Settings.

2. Go to the Dynamic Settings tab and locate the INSTALLMENT_FILTERS setting.

3. Add or edit the appropriate filter configurations.

• The priority order of installment filters is important. Filters are applied in the specified sequence.

• For example, if a product meets both a category filter and a basket amount filter, the order of application can affect the installment options displayed to the end user.

• Incorrect ordering can negatively impact the user experience, so filters must be configured carefully.

Default Setting:

{
    "klass": "omnishop.payments.filters.ProductInstallmentFilter",
    "kwargs": {
        "max_installment_field": "max_installment",
        "message": _("We can't do installments for your basket because of "
                     "the product named {product_name}. If you want your "
                     "basket to be done installments, we recommend you to "
                     "make a seperated order for this product in your "
                     "basket."),
    }
}

Filter Types and Functions

1. Category Installment Filter

This filter enforces category-specific installment limits, applying the maximum installment options allowed for each product category in line with legal regulations or business rules.

For every product in the basket, its category is checked, and the maximum installment field (max_installment_field) defined for that category is evaluated.

If a category has a max_installment_field value specified, the available installment options will be limited so as not to exceed this value. The user will only see installment options that fall within this limit.

Features:

• The max_installment_field key is not a fixed attribute. The maximum installment field defined on the category attribute is specified dynamically through the kwargs parameters within the Category Installment Filter.

• If the product name is to be displayed in the message, the {product_name} variable can be used. No variables other than {product_name} can be defined.

Kwargs Parameters:

Key	Type	Description
max_installment_field	string	The key of the field on the category attribute that defines the maximum number of installments.
message	string	The message to be displayed to the user. The {product_name} variable can be used in the message.

Example Kwargs:

{
  "max_installment_field": "max_installment_key",
  "message": "You can choose up to 3 installments for the product {product_name}."
}

Explanation:

• During the basket check, the max_installment_key value for the category of each product in the basket is retrieved.

• For example, if a category’s max_installment_key value is set to 3, only installment options of 3 or fewer will be offered to the user for products in that category.

---

2. Category Special Installment Filter

The Category Special Installment Filter is used to limit installment options based on attribute values within the category tree. This filter checks not only the attribute values of a category itself but also those of its hierarchical parent categories.

If a category has a max_installment_options field defined, the filtering is performed using this field. This allows offering specific installment options to users based on product price or category-specific rules.

Features:

• Installment Limitation with a Price Threshold:

  • If a product price is equal to or greater than the threshold_price, the installment options listed in the installment_list_gte field will apply.

  • If a product price is less than the threshold_price, the installment options listed in the installment_list_lt field will apply.

• Installment Limitation Without a Price Threshold:

  • If a price threshold is not required, simply set the installment_list value for the category to define valid installment options.

• Category Tree Hierarchy:

  • The filter also checks the parent categories in the category tree. If a parent category has max_installment_options defined, it will also be taken into account.

Category Attribute Examples:

1. Installment Limitation Based on Price Threshold:

{
  "max_installment_options": {
    "threshold_price": "5000.00",
    "installment_list_gte": "2,3,6,9",
    "installment_list_lt": "2,3,6"
  }
}

Explanation:

• If the product price is 5,000.00 ₺ or more, only 2, 3, 6, and 9 installment options will be available.

• If the product price is less than 5,000.00 ₺, only 2, 3, and 6 installment options will be available.

2. Installment Limitation Without a Price Threshold:

{
  "max_installment_options": {
    "installment_list": "2,3,6"
  }
}

Explanation:

• Only 2, 3, and 6 installment options will be available for products in this category.

• installment_list_gte and installment_list_lt format:

  • These values must be strings, with no spaces, and separated by commas.

    • Example: "2,3,6"

  • If no limitation is required for a specific price range, the installment_list_gte and/or installment_list_lt fields may be left empty or set to null.

• installment_list format:

  • Must be a comma-separated string with no spaces.

    • Example: "2,3,6"

• When max_installment_options is not defined for the category:

  • If the categories of the products in the basket do not have max_installment_options defined, no filtering will be applied.

Dynamic Settings Configuration:

• Under INSTALLMENT_FILTERS dynamic setting, the kwargs field should be set as {}.

---

3. Commerce Card Installment Filter

The Commerce Card Installment Filter filters installment options that are only valid for business credit cards. When the user pays with a business card, this filter is activated and displays only the installment options applicable to business cards.

This filter not only applies special installment limitations for business cards but also prevents other filters from being applied, ending the filtering process for business card transactions. As a result, only the rules defined within this filter apply for users paying with a business card.

Features:

• Business Card Check:

  • Determines whether the card used by the user is a business credit card.

  • If the card is not a business card, this filter is skipped and the next filters are applied.

  • If the card is a business card, the Commerce Card Installment Filter is applied and no subsequent filters are executed.

Dynamic Settings Configuration:

• Under INSTALLMENT_FILTERS dynamic setting, the kwargs field should be set as {}.

---

4. Category Special Installment Commerce Card Filter

The Category Special Installment Commerce Card Filter determines the valid installment options for products in specific categories only when payment is made with a business credit card. This filter evaluates the category attributes of products, considering both the current category and any attributes defined in its parent categories in the category tree.

The filter uses the max_commerce_card_installment_options field defined in category attributes. If this field is set, it determines the valid installment options based on the basket price and category-specific rules. If a business card is not used, this filter is skipped.

Features:

• Category Attribute-Based Filtering:

  • Checks the max_commerce_card_installment_options field in categories.

  • Defines the maximum installment limits applicable for business credit cards.

• Dynamic Filtering Based on Basket Price:

  • If a threshold_price is defined, the total basket amount is compared against it:

    • If the product price is equal to or greater than the threshold, the installment options in installment_list_gte apply.

    • If the product price is less than the threshold, the installment options in installment_list_lt apply.

• Fixed Installment List:

  • If a price-independent installment restriction is needed, the installment_list field can be used.

• Business Card Requirement:

  • If payment is not made with a business card, the filter does not run.

Category Attribute Examples:

1. Installment Limitation Based on Price Threshold:

{
  "max_commerce_card_installment_options": {
    "threshold_price": "5000.00",
    "installment_list_gte": "2,3,6,9",
    "installment_list_lt": "2,3,6"
  }
}

• threshold_price: 5,000.00 ₺

• installment_list_gte: Applicable installment options for prices 5,000.00 ₺ and above → (2, 3, 6, 9)

• installment_list_lt: Applicable installment options for prices below 5,000.00 ₺ → (2, 3, 6)

2. Installment Limitation Without Price Threshold:

{
  "max_commerce_card_installment_options": {
    "installment_list": "2,3,6"
  }
}

• Valid installment options for all price ranges → (2, 3, 6)

• installment_list_gte and installment_list_lt format:

  • Values must be provided as a comma-separated string with no spaces.

    • Example: "2,3,6"

  • If no limitation is required for a certain price range, these fields may be left empty or set to null.

• installment_list format:

  • Must be a comma-separated string with no spaces.

    • Example: "2,3,6"

• If max_commerce_card_installment_options is not defined:

  • If the categories of the products in the basket do not have max_commerce_card_installment_options defined, or if the payment card is not a business card, no filtering is applied.

• Filter order recommendation:

  • When this filter is applied, no subsequent filters will be executed for business card payments. For this reason, it is recommended to place this filter early in the filter order to prevent it from being affected by other filters.

Dynamic Settings Configuration:

• Under INSTALLMENT_FILTERS dynamic setting, the kwargs field should be set as {}.

---

5. Product Installment Filter

The Product Installment Filter is used to determine the maximum number of installments for each product in the basket based on its own attributes. This filter checks a specific field defined in the product’s attribute (max_installment_field) and offers installment options customized per product.

Features:

• Product-Based Installment Restriction:

  • The value of the max_installment_field in each product’s attribute is checked to limit the available installment options.

  • If a value is specified for a product’s max_installment_field, no installment option exceeding that value will be offered.

• Message Display:

  • The message shown to the user can include dynamic information such as the product name.

  • The message is defined in the message key inside kwargs and may include the {product_name} variable.

  • Dynamic messages using variables other than {product_name} are not supported.

Kwargs Parameters:

Key	Type	Description
max_installment_field	string	The key of the field in the product’s attribute that holds the maximum installment count.
message	string	The message to display to the user. Can include the {product_name} variable.

Example Kwargs:

{
  "max_installment_field": "max_installment_key",
  "message": "{product_name} can be purchased in up to 2 installments."
}

• The max_installment_key value of each product in the basket is checked.

• If any product has a maximum installment limit, the entire basket transaction will be restricted accordingly.

Example Scenario:

If a product in the basket has its max_installment_key value set to 2, the maximum installment option for all products in the basket will be limited to 2 installments.

---

6. Attribute Filter

The Attribute Filter is used to restrict installment options based on specific attributes of products. When applied, it limits the installment options according to a given attribute value of a product in the basket, while allowing certain values to be excluded from restriction. If a product’s attribute value is included in the specified exclude_values list, no filtering is applied.

Features:

• Exclude Values:

  • Products with attribute values listed in exclude_values are excluded from installment restrictions.

  • If any product in the basket has a value from the exclude_values list, the installment_limit parameter is ignored and no restriction is applied.

• Installment Limit:

  • If the product’s attribute value does not match any value in the exclude_values list, the installment_limit value is used to restrict the maximum installment option.

Kwargs Parameters:

Key	Type	Description
attribute_field	string	The attribute key to be checked on the product.
exclude_values	list[string]	List of attribute values to be excluded from the maximum installment filter.
installment_limit	string	The maximum installment limit allowed for the basket.

Example Kwargs:

{
  "exclude_values": ["XL"],
  "attribute_field": "size",
  "installment_limit": "8"
}

Explanation:

• If none of the products in the basket have a size attribute value of XL, the maximum installment number is limited to 8.

• If the size attribute value is XL, no installment restriction is applied.

---

7. Basket Amount Filter

The Basket Amount Filter is used to restrict installment options based on the total amount of the basket. This filter offers different installment options depending on the basket total. For example, baskets exceeding a certain price threshold may be offered more flexible installment options. As the basket amount increases, installment options can become more flexible.

Features:

• Installment Limit Based on Basket Amount:

  • The basket total is checked against min_limit and max_limit values.

  • These limits are defined in the config section of the installment object and are used to restrict the number of installments within these bounds.

  • Depending on whether the basket total exceeds, falls within, or is below these limits, the available installment options are filtered accordingly.

Dynamic Settings Configuration:

• Under INSTALLMENT_FILTERS dynamic setting, the kwargs field should be set as {}.

---

8. Attribute Set Filter

The Attribute Set Filter restricts the maximum number of installments based on whether products belong to a specific attribute set. This filter only applies to products with the defined attribute sets and limits their installment options according to the specified rules.

Features:

• Installment Limit by Attribute Set IDs:

  • For products with specific attribute_set_ids, the maximum installment count is restricted.

  • If a product in the basket has one of the specified attribute_set_ids, the maximum number of installments allowed for that product is limited by max_installment.

Kwargs Parameters:

Key	Type	Description
attribute_set_ids	list[Integer]	List of attribute set IDs to which the restriction applies.
max_installment	string	Maximum number of installments allowed for the basket.
message	string	Message displayed to the user. No variables are used in the message.

Example Kwargs:

{
  "max_installment": "7",
  "attribute_set_ids": [10],
  "message": "You can choose up to 7 installments for these products."
}

Explanation:

• If any product in the basket has attribute_set_id 10, the maximum number of installments for the basket will be limited to 7.

• The user will see the message: "You can choose up to 7 installments for these products."

---

9. Duplicate Installment Filter

The Duplicate Installment Filter matches the installment options of products in the basket based on specific attribute values and presents the corresponding installment options to the user. The attribute values of the products in the basket are checked against the values defined in the kwargs parameters, and only matching installment options are offered.

Features:

• Installment Options Based on Product Attribute Value:

  • If any product in the basket has a specific attribute value that matches the product_attribute_key and product_attribute_value defined in kwargs, only the installment options corresponding to that match are filtered and applied.

  • Products with non-matching attribute values will have different installment options applied.

  • These keys and values are defined in the config section of the installment object.

Kwargs Parameters:

Key	Type	Description
product_attribute_key	string	Specifies the attribute key to check on the product.
product_attribute_value	any	Specifies the value corresponding to the attribute key on the product.

Example Kwargs:

{
    "product_attribute_key": "payment_type",
    "product_attribute_value": "interest free"
}

Explanation:

• If any product in the basket has a payment_type attribute value of "interest free", the installment options defined for "payment_type": "interest free" can be applied.

• If none of the products have the payment_type: "interest free" attribute value, the installment options are filtered among the ones not associated with payment_type.

---

10. Currency Installment Filter

The Currency Installment Filter restricts installment options based on the currency used for payment. If the payment currency is not one of the currencies listed in installment_allowed_currencies, only a single installment option (1 installment) is offered. Otherwise, if the payment currency is included in the allowed list, there is no restriction on the number of installments.

Kwargs Parameters:

Key	Type	Description
installment_allowed_currencies	list[string]	List of allowed currencies for installment payments.

Example Kwargs:

{
    "installment_allowed_currencies": ["try", "usd"]
}

Explanation:

• If the payment currency in the basket is not TRY or USD, the installment options are limited to 1 installment only.

• If the payment currency is TRY or USD, there is no restriction on the number of installments, and all applicable installment options remain valid.

---

11. Email Domain Installment Filter

The Email Domain Installment Filter is used to condition installment options based on the user's email domain and/or whether their email address has been verified. This filter allows merchants to restrict available installment options for specific user groups, enhancing payment control and targeted campaign rules.

Features:

• Email Verification Requirement:

  • email_verification_required: true → The filter applies only if the user’s email is verified.

  • email_verification_required: false → The filter applies regardless of the user’s email verification status.

• Domain-Based Restriction:

  • The email_domains list defines which email domains the filter applies to.

  • Only users with email addresses matching the domains will have the installment options restricted.

• Combined Conditions:

  • Both email_verification_required and email_domains can be used together or independently.

Configuration Examples in Card Settings

1. Restrict to Verified Emails from a Specific Domain:

{
  "config": {
    "email_verification_required": true,
    "email_domains": ["akinon.com"]
  }
}

Explanation:

Only users with a verified email address from the akinon.com domain will see installment options restricted by this filter.

2. Restrict to a Specific Domain Without Verification Requirement:

{
  "config": {
    "email_verification_required": false,
    "email_domains": ["akinon.com"]
  }
}

Explanation:

Users with any akinon.com email address, verified or not, will have installment options filtered accordingly.

When the Configuration is Not Defined:

• If email_verification_required and email_domains are not defined in the card settings, no filtering will be applied.

Card Settings Configuration:

• The filter is applied via Card Settings, and the kwargs field must be set as {} under the INSTALLMENT_FILTERS configuration in Dynamic Settings.

---

12. Email Domain Select Installment Filter

The Email Domain Select Installment Filter provides the ability to restrict installment options based on the user’s email domain. This feature allows users with specific email domains to transact with a predefined maximum installment limit.

Features:

• Domain-Based Installment Restriction:

  • Users with email addresses belonging to the specified domains are limited to the number of installments defined in select_installment.

  • The operator parameter determines the comparison method (e.g., <=, <, ==, >, >=) for filtering the installment options.

• Email Verification Requirement:

  • email_verification_required: false → The filter applies even if the user’s email address is not verified.

  • email_verification_required: true → The filter does not apply if the user’s email address is unverified, even if the domain matches.

Kwargs Parameters:

Key	Type	Description
operator	string	Comparison operator for limiting installments (<=, <, ==, >, >=).
email_domains	list[string]	List of allowed email domains for the installment limit.
select_installment	integer	Maximum number of installments allowed for matching domains.

Example Kwargs 1:

{
    "operator": "<=",
    "email_domains": ["akinon.com"],
    "select_installment": 3
}

Explanation:

• Users with the akinon.com domain can only perform transactions with 3 installments or fewer.

Example Kwargs 2:

{
    "operator": ">",
    "email_domains": ["akinon.com", "gmail.com"],
    "select_installment": 3
}

Explanation:

• Users with akinon.com or gmail.com emails will see installment options greater than 3 (e.g., 4, 6, 9, 12).

• The filter respects both the email domain and verification status.

• Different domains not included in the filter are unaffected, and default installment options remain available.