# 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.

## <mark style="color:red;">**Filter Types and Descriptions**</mark>

The filters used in installment filtering are listed below.

<table><thead><tr><th width="219.0859375">Class</th><th width="149.75">Label</th><th>Description</th></tr></thead><tbody><tr><td><code>omnishop.payments.filters.CategoryInstallmentFilter</code></td><td>Category Installment Filter</td><td>Limits installments based on product categories. For example, electronic products may have a maximum of 6 installments.</td></tr><tr><td><code>omnishop.payments.filters.CategorySpecialInstallmentFilter</code></td><td>Category Special Installment Filter</td><td>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.</td></tr><tr><td><code>omnishop.payments.filters.CommerceCardInstallmentFilter</code></td><td>Commerce Card Installment Filter</td><td>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.</td></tr><tr><td><code>omnishop.payments.filters.CategorySpecialInstallmentCommerceCardFilter</code></td><td>Category Special Installment Commerce Card Filter</td><td>Provides category-based special installment limitations for commercial cards. For example, a maximum of 6 installments for white goods when using a commercial card.</td></tr><tr><td><code>omnishop.payments.filters.ProductInstallmentFilter</code></td><td>Product Installment Filter</td><td>Limits installments based on specific product attributes. For example, discounted products may not be eligible for installments.</td></tr><tr><td><code>omnishop.payments.filters.AttributeFilter</code></td><td>Attribute Filter</td><td>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.</td></tr><tr><td><code>omnishop.payments.filters.BasketAmountFilter</code></td><td>Basket Amount Filter</td><td>Limits installment options according to the total basket amount. For example, installments may not be available for purchases under 500 ₺.</td></tr><tr><td><code>omnishop.payments.filters.AttributeSetFilter</code></td><td>Attribute Set Filter</td><td>Configures installment options based on products with a specific attribute set. For example, a maximum of 3 installments for products with a “premium” feature.</td></tr><tr><td><code>omnishop.payments.filters.DuplicateInstallmentFilter</code></td><td>Duplicate Installment Filter</td><td>Matches installment options based on specific attribute values of products in the basket and provides suitable installment options based on these matches.</td></tr><tr><td><code>omnishop.payments.filters.CurrencyInstallmentFilter</code></td><td>Currency Installment Filter</td><td>Limits installments according to the currency used in the basket. For example, installments may only be available for transactions in TRY.</td></tr><tr><td><code>omnishop.payments.filters.EmailInstallmentFilter</code></td><td>Email Domain Installment Filter</td><td>Limits available installment options based on the user's email domain and a specified comparison operator. For example, users with an <code>akinon.com</code> email may only see installments less than or equal to 3.</td></tr><tr><td><code>omnishop.payments.filters.EmailSelectInstallmentFilter</code></td><td>Email Domain Select Installment Filter</td><td>Applies installment filtering rules based on email verification status and/or email domain. For example, only verified <code>akinon.com</code> users may access certain installment options.</td></tr></tbody></table>

## <mark style="color:red;">**Configuring Installment Filters with Dynamic Setting**</mark>

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.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcgNfH5DhquiKNoXdPuuiCnrGgmNZmbP42hROyUVUlwl16mGtSEP8Ez3birCPosDBjhMYeD9xbXByWPmp1T6AluUXLe1jFtuibji4NNFIJiZRAjH9BVNyVVPNRLnWmRhoem5XaQFw?key=Ep9ZlotKtem7s2sVrAUX39rj" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}

* 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.
  {% endhint %}

#### **Default Setting:**

```json
{
    "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."),
    }
}
```

## <mark style="color:red;">**Filter Types and Functions**</mark>

### <mark style="color:red;">**1. Category Installment Filter**</mark>

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

<table><thead><tr><th width="213.26171875">Key</th><th width="84.4765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>max_installment_field</code></td><td>string</td><td>The key of the field on the category attribute that defines the maximum number of installments.</td></tr><tr><td><code>message</code></td><td>string</td><td>The message to be displayed to the user. The <code>{product_name}</code> variable can be used in the message.</td></tr></tbody></table>

#### **Example Kwargs:**

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

***

### <mark style="color:red;">**2. Category Special Installment Filter**</mark>

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.

#### <mark style="color:red;">**Category Attribute Examples:**</mark>

#### **1. Installment Limitation Based on Price Threshold:**

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

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

**Explanation:**

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

{% hint style="warning" %}

* **`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.
    {% endhint %}

#### **Dynamic Settings Configuration:**

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

***

### <mark style="color:red;">**3. Commerce Card Installment Filter**</mark>

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 `{}`.

***

### <mark style="color:red;">**4. Category Special Installment Commerce Card Filter**</mark>

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.

#### <mark style="color:red;">**Category Attribute Examples:**</mark>

#### **1. Installment Limitation Based on Price Threshold:**

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

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

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

{% hint style="warning" %}

* **`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.
    {% endhint %}

#### **Dynamic Settings Configuration:**

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

***

### <mark style="color:red;">5. Product Installment Filter</mark>

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

<table><thead><tr><th width="203.87109375">Key</th><th width="81.10546875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>max_installment_field</code></td><td>string</td><td>The key of the field in the product’s attribute that holds the maximum installment count.</td></tr><tr><td><code>message</code></td><td>string</td><td>The message to display to the user. Can include the <code>{product_name}</code> variable.</td></tr></tbody></table>

**Example Kwargs:**

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

***

### <mark style="color:red;">**6. Attribute Filter**</mark>

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

<table><thead><tr><th width="175.296875">Key</th><th width="106.59765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>attribute_field</code></td><td>string</td><td>The attribute key to be checked on the product.</td></tr><tr><td><code>exclude_values</code></td><td>list[string]</td><td>List of attribute values to be excluded from the maximum installment filter.</td></tr><tr><td><code>installment_limit</code></td><td>string</td><td>The maximum installment limit allowed for the basket.</td></tr></tbody></table>

#### **Example Kwargs:**

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

***

### <mark style="color:red;">**7. Basket Amount Filter**</mark>

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 `{}`.

***

### <mark style="color:red;">**8. Attribute Set Filter**</mark>

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_id`s, the maximum number of installments allowed for that product is limited by `max_installment`.

#### **Kwargs Parameters:**

<table><thead><tr><th width="174.79296875">Key</th><th width="109.7890625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>attribute_set_ids</code></td><td>list[Integer]</td><td>List of attribute set IDs to which the restriction applies.</td></tr><tr><td><code>max_installment</code></td><td>string</td><td>Maximum number of installments allowed for the basket.</td></tr><tr><td><code>message</code></td><td>string</td><td>Message displayed to the user. No variables are used in the message.</td></tr></tbody></table>

#### **Example Kwargs:**

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

***

### <mark style="color:red;">**9. Duplicate Installment Filter**</mark>

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

<table><thead><tr><th width="223.18359375">Key</th><th width="93.58203125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>product_attribute_key</code></td><td>string</td><td>Specifies the attribute key to check on the product.</td></tr><tr><td><code>product_attribute_value</code></td><td>any</td><td>Specifies the value corresponding to the attribute key on the product.</td></tr></tbody></table>

#### **Example Kwargs:**

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

***

### <mark style="color:red;">**10. Currency Installment Filter**</mark>

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

<table><thead><tr><th width="277.75">Key</th><th width="99.4765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>installment_allowed_currencies</code></td><td>list[string]</td><td>List of allowed currencies for installment payments.</td></tr></tbody></table>

#### **Example Kwargs:**

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

***

### <mark style="color:red;">11. Email Domain Installment Filter</mark>

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.

#### <mark style="color:red;">**Configuration Examples in Card Settings**</mark>

#### **1. Restrict to Verified Emails from a Specific Domain:**

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

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

{% hint style="warning" %}
**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.
  {% endhint %}

***

### <mark style="color:red;">**12. Email Domain Select Installment Filter**</mark>

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

<table><thead><tr><th width="182.6171875">Key</th><th width="103.55859375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>operator</code></td><td>string</td><td>Comparison operator for limiting installments (<code>&#x3C;=</code>, <code>&#x3C;</code>, <code>==</code>, <code>></code>, <code>>=</code>).</td></tr><tr><td><code>email_domains</code></td><td>list[string]</td><td>List of allowed email domains for the installment limit.</td></tr><tr><td><code>select_installment</code></td><td>integer</td><td>Maximum number of installments allowed for matching domains.</td></tr></tbody></table>

#### **Example Kwargs 1:**

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

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

{% hint style="warning" %}

* 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.
  {% endhint %}