> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/commerce/dynamic-settings.md).

# Dynamic Settings

Dynamic settings allow for the flexible and customizable management of various aspects of your system. This document provides an overview of the key configurations available through dynamic settings, each designed to address specific operational needs and enhance the functionality of your platform.

### **1. Subscription Gateways**

Defines the subscription / marketing gateways (e.g. Emarsys, Setrow, Insider, EuroMessage, Mobildev) used to sync users and their consent / preference data to external CRM and newsletter providers. Each entry is keyed by a gateway slug and holds the configuration (credentials, endpoint URLs, options, optional user-matching rule) needed to talk to one provider account.

A single store can host multiple regional or brand accounts of the same provider side by side. Attaching a `match_user` rule to an entry scopes that gateway to a subset of users, so the same shop can fan out to several regional accounts (for example one Emarsys account for Turkey and another for France) without writing duplicate records to the wrong account.

Key: `SUBSCRIPTION_GATEWAYS`\
Type: object (dict of gateway slug → gateway config)

**Entry fields**

| Field             | Type   | Required | Description                                                                                                                          |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `klass`           | string | Yes      | Identifier of the gateway implementation to use. Must be one of the supported provider values.                                       |
| `dispatch_klass`  | string | Yes      | Identifier of the dispatch handler that routes calls to the gateway. Most providers use the generic dispatcher; Setrow uses its own. |
| `conf`            | object | Yes      | Provider-specific configuration: credentials, endpoints, unique field, and any other provider options.                               |
| `conf.auth`       | object | Yes      | Credentials block (e.g. username / secret, API key) required by the provider.                                                        |
| `conf.match_user` | object | No       | Optional rule that limits this gateway to users whose attributes match (see below).                                                  |

**`match_user` — user-based routing for multi-region setups**

When `match_user` is present, the gateway is invoked for a user only if that user's attribute equals the configured value. Entries without `match_user` keep the legacy single-region behaviour and run for every user.

| Field       | Type   | Required | Description                                                                      |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `attribute` | string | Yes      | Name of the user attribute to check (e.g. `country_code`). Cannot be empty.      |
| `equals`    | string | Yes      | Value the attribute must equal for this gateway to be selected. Cannot be empty. |

**Routing behaviour**

* A gateway **without** `match_user` runs for every user.
* A gateway **with** `match_user` runs only when the user's attribute equals the configured value; non-matching users are skipped.
* When the subscription call has no user context (anonymous newsletter signup using only an email), every gateway that defines `match_user` is skipped. Without knowing which region the user belongs to, sending the request to all regional accounts would create duplicate records — so the safer default is to skip.
* Removing `match_user` from an entry that previously had one silently widens the gateway to **all** users and starts writing into the wrong regional account. To retire a region, delete the entry entirely instead of clearing `match_user`.

**Example — single region**

```json
{
  "emarsys": {
    "klass": "omnishop.libs.subscription_gateways.emarsys.gateway.EmarsysGateWay",
    "dispatch_klass": "omnishop.libs.subscription_gateways.service.GenericDispatchService",
    "conf": {
      "auth": {"username": "...", "secret": "..."},
      "contact_url": "https://api.emarsys.net/api/v2/contact/?create_if_not_exists=1",
      "query_contact_url": "https://api.emarsys.net/api/v2/contact/query/",
      "unique_field": "email"
    }
  }
}
```

**Example — multi-region (Emarsys TR + FR)**

```json
{
  "emarsys_tr": {
    "klass": "omnishop.libs.subscription_gateways.emarsys.gateway.EmarsysGateWay",
    "dispatch_klass": "omnishop.libs.subscription_gateways.service.GenericDispatchService",
    "conf": {
      "auth": {"username": "tr_user", "secret": "tr_secret"},
      "contact_url": "https://api.emarsys.net/api/v2/contact/?create_if_not_exists=1",
      "query_contact_url": "https://api.emarsys.net/api/v2/contact/query/",
      "unique_field": "email",
      "match_user": {"attribute": "country_code", "equals": "TR"}
    }
  },
  "emarsys_fr": {
    "klass": "omnishop.libs.subscription_gateways.emarsys.gateway.EmarsysGateWay",
    "dispatch_klass": "omnishop.libs.subscription_gateways.service.GenericDispatchService",
    "conf": {
      "auth": {"username": "fr_user", "secret": "fr_secret"},
      "contact_url": "https://api-fr.emarsys.net/api/v2/contact/?create_if_not_exists=1",
      "query_contact_url": "https://api-fr.emarsys.net/api/v2/contact/query/",
      "unique_field": "email",
      "match_user": {"attribute": "country_code", "equals": "FR"}
    }
  }
}
```

With this setup:

* A user whose `country_code` attribute is `TR` is synced to `emarsys_tr`.
* A user whose `country_code` attribute is `FR` is synced to `emarsys_fr`.
* A user with no `country_code` (or a different value) is not synced to either gateway.
* An anonymous email-only subscription is not synced to either gateway, preventing cross-region duplicate records.

**Related settings**

* `ACTIVE_SUBSCRIPTION_GATEWAYS` — list of gateway slugs that are turned on. Only entries listed here participate in dispatch; it does not have to include every key in `SUBSCRIPTION_GATEWAYS`.
* `SUBSCRIPTION_ACTIVE` — master switch. When `false`, no subscription dispatch runs regardless of the configuration here.

### **2. Default Country Code**

The ISO country code (e.g. `tr`, `pl`, `en`) used as the default market for the brand. It must match an existing `Country` record (by `code`). This value is used to pre-select the country on address forms, resolve country-dependent resources (e.g. LCW SSO), and provide a default country in loyalty/subscription flows (e.g. Emarsys). It affects checkout address pages, user resources, and SSO gateways that need a single default country.

**Usage:** Used in `omnishop.orders.pages.address` and `omnishop.users.resources.views` via `CountryService().get_country(dynamic_settings.DEFAULT_COUNTRY_CODE)`; in `omnishop.address.jinja_globals` for templates; and in subscription gateways (e.g. Emarsys) when a default country is required.

Key: `DEFAULT_COUNTRY_CODE`\
Type: string

**Example:** `"tr"` (Turkey), `"pl"` (Poland), `"en"` (if used as a country code in your data).

### **3. Identity Number Validator**

Dotted path to the callable that validates the address identity number (e.g. national ID). The validator is invoked when address data is validated; it receives the identity number value and must raise if invalid. Use this to enforce country-specific rules (e.g. Turkish ID format) or to disable validation.

**Usage:** Loaded in `omnishop.address.resources.serializers` with `import_string(dynamic_settings.IDENTITY_NUMBER_VALIDATOR)` and called during address validation.

Key: `IDENTITY_NUMBER_VALIDATOR`\
Type: string (dotted path)

**Example:**

* `omnicore.address.validators.null_identity_validator` — no validation.
* `omnicore.address.validators.tc_identity_number_validator` — Turkish Republic identity number format.

### **4. Default Shipping Cost**

Fallback shipping cost (numeric or string that parses to decimal) used when no matching `ShippingCost` rule is found for the given address (country, city, township, district) and currency. If a rule exists for a more specific region it overrides this; otherwise the checkout and shipping calculator use this value so the order still has a defined shipping amount.

**Usage:** In `omnishop.address.service.ShippingCostService.get_cost()`: if there is no shipping address, or no `ShippingCost` row matches the address hierarchy, the method returns `Decimal(dynamic_settings.DEFAULT_SHIPPING_COST)`.

Key: `DEFAULT_SHIPPING_COST`\
Type: number (int/float) or string

**Example:** `0`, `"0.00"`, or `9.99`.

### **5. Sitemap Configuration**

Configures XML sitemap generation comprehensively. Each content type (product, category, page, etc.) can be individually enabled/disabled with its own crawl frequency, priority, limit, and filters. When this setting is saved, the sitemap is automatically regenerated.

**Post-Save Behaviour:** When this value is saved, the sitemap is automatically regenerated.

Key: `SITEMAP_CONFIGURATION`\
Type: object (nested dict)\
Validation: Each sitemap type is validated with its own rules

**Top-level keys:**

| Key            | Content type   |
| -------------- | -------------- |
| `category`     | Category pages |
| `flat_page`    | Static pages   |
| `landing_page` | Landing pages  |
| `product`      | Product pages  |
| `special_page` | Special pages  |

**Common fields for each content type:**

| Field                | Type      | Default         | Description                                                           |
| -------------------- | --------- | --------------- | --------------------------------------------------------------------- |
| `enabled`            | `boolean` | —               | Whether this content type is included in the sitemap                  |
| `changefreq`         | `string`  | —               | Crawl frequency hint for search engines                               |
| `priority`           | `float`   | —               | Crawl priority (0.0 – 1.0)                                            |
| `limit`              | `integer` | —               | Maximum URL count per page (1 – 50000)                                |
| `template`           | `string`  | `"sitemap.xml"` | Sitemap template to use                                               |
| `i18n`               | `boolean` | —               | Generate a separate sitemap per language                              |
| `should_generate`    | `boolean` | `true`          | Whether generation is triggered                                       |
| `exclude_changefreq` | `boolean` | `false`         | When `true`, the `<changefreq>` element is not written to the sitemap |
| `exclude_priority`   | `boolean` | `false`         | When `true`, the `<priority>` element is not written to the sitemap   |
| `excludes`           | `dict`    | `{}`            | Filter for records to exclude from sitemap                            |
| `filters`            | `dict`    | `{}`            | Filter for records to include in sitemap                              |

**Valid `changefreq` values:** `always` · `hourly` · `daily` · `weekly` · `monthly` · `yearly` · `never`

**Additional fields for `product`:**

| Field                          | Type      | Description                                                                                                                                                                                      |
| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `include_stock_out_products`   | `boolean` | Include out-of-stock products in the sitemap                                                                                                                                                     |
| `max_image_count`              | `integer` | Maximum number of images per product in the sitemap                                                                                                                                              |
| `include_seller_id_param`      | `boolean` | When `true`, appends `?seller_id=<id>` to each product URL using the cheapest active offer's seller ID. If no active offer exists, the URL is listed without the parameter. Defaults to `false`. |
| `exclude_end_of_life_products` | `boolean` | When `true`, products whose `PRODUCT_END_OF_LIFE_ATTRIBUTE` attribute is `true` and that have no stock are left out of the sitemap. Defaults to `false`.                                         |

**Special validation rule:** When `product` uses `template: "sitemap_with_images.xml"`, the `limit` must not exceed **20000**.

**SEO and performance considerations:**

* `enabled: false` → All URLs for that content type are removed from the sitemap; search engines cannot rediscover those pages
* `include_stock_out_products: true` → Out-of-stock products remain in the sitemap, preserving SEO continuity
* Setting `limit` too low may leave thousands of URLs out of the sitemap
* Excessively high `changefreq` + `priority` wastes search engine crawl budget
* `i18n: true` generates a separate sitemap per language — required for multi-language projects

**Example:**

```json
{
  "category": {
    "enabled": true,
    "changefreq": "weekly",
    "priority": 0.8,
    "limit": 50000,
    "i18n": false,
    "should_generate": true,
    "excludes": {},
    "filters": {}
  },
  "product": {
    "enabled": true,
    "changefreq": "daily",
    "priority": 1.0,
    "limit": 20000,
    "template": "sitemap_with_images.xml",
    "i18n": false,
    "should_generate": true,
    "include_stock_out_products": false,
    "max_image_count": 5,
    "excludes": {},
    "filters": {}
  },
  "flat_page": {
    "enabled": true,
    "changefreq": "monthly",
    "priority": 0.5,
    "limit": 1000,
    "i18n": false,
    "should_generate": true,
    "excludes": {},
    "filters": {}
  },
  "landing_page": {
    "enabled": false,
    "changefreq": "weekly",
    "priority": 0.6,
    "limit": 10000,
    "i18n": false,
    "should_generate": true,
    "excludes": {},
    "filters": {}
  },
  "special_page": {
    "enabled": false,
    "changefreq": "weekly",
    "priority": 0.7,
    "limit": 5000,
    "i18n": false,
    "should_generate": true,
    "excludes": {},
    "filters": {}
  }
}
```

### **6. Customer Loyalty Card Service**

Selects the loyalty-card backend and its options. The `klass` is the dotted path of the service class (e.g. default, Akipay, Zubizu, Tefal, Obase, Como, Giz, Loccitane, Nebim, Rapidpromo); `conf` is a free-form object used for API URLs, auth, minimum basket amount, JWT path, etc. This service is used for loyalty views (create/update cards, query points), promotion flows that need card data, and user views that show or link loyalty information.

**Usage:** Read in `omnishop.loyaltycard.views`, `omnishop.loyaltycard.client`, `omnishop.promotions.service`, and `omnishop.users.views`; the client uses `conf` for auth (e.g. `auth.auth_url`, `jwt_token_path`) and optional `minimum_basket_amount` (decimal, ≥ 0).

Key: `CUSTOMER_LOYALTY_CARD_SERVICE`\
Type: object

**Example:**

```
{
    "klass": "omnishop.loyaltycard.service.DefaultLoyaltyCardService",
    "conf": {
        "auth": {
            "auth_url": "https://api.example.com/auth",
            "token_expiration": 3600
        },
        "jwt_token_path": ["Data", "Token"],
        "minimum_basket_amount": "100.00"
    }
}
```

### **7. Cash Register Authentication Configuration**

Credentials used to authenticate requests that originate from a Cash Register (e.g. creating or accessing a pre-order by order number). The incoming request’s username and password are compared to this setting; only when both match is the operation allowed. This protects cash-register-only endpoints from unauthorized use.

**Usage:** In `omnishop.orders.resources.views.check_user_name()`: `conf = dynamic_settings.CASH_REGISTER_AUTH_CONF` and validation succeeds when `data.get("username") == conf['username']` and `data.get("password") == conf['password']`. Referenced from supervising/API views that need to expose or validate this key.

Key: `CASH_REGISTER_AUTH_CONF`\
Type: object

**Example:**

```
{
    "username": "cr_user",
    "password": "secure_cr_password"
}
```

### **8. Three D Secure Enabled**

Master switch for 3D Secure (3DS) on payment flows. When `true`, the payment pipeline may require a 3DS step (e.g. redirect to issuer) depending on POS/card configuration and `THREE_D_SECURE_RULES`. When `false`, 3DS is not applied regardless of rules. Used together with POS/card `three_d_enabled` and the rule functions that decide per request whether to trigger 3DS (e.g. by amount, guest user, currency).

**Usage:** Checked in `omnishop.orders.rules.check_three_d_secure()`: if `not dynamic_settings.THREE_D_SECURE_ENABLED` the function returns `False` and 3DS is skipped. Also used in `is_first_order` and related tests.

Key: `THREE_D_SECURE_ENABLED`\
Type: boolean

**Example:** `true` to enable 3DS when rules and POS/card allow; `false` to disable globally.

### **9. Three D Secure Rules**

List of rule entries that decide whether to apply 3D Secure for a given payment. Each entry has `klass` (dotted path to a rule function) and `defaults` (kwargs passed to that function). 3DS is applied only when `THREE_D_SECURE_ENABLED` is true, POS/card allow it, and at least one rule returns true (or the list is empty). Rule functions receive payment context (pos, user, amount, currency, etc.) and return a boolean.

**Where it is used**

* **omnishop.orders.rules.check\_three\_d\_secure()** — `rules = dynamic_settings.THREE_D_SECURE_RULES`; each rule's `klass` is imported and called with `defaults` merged with kwargs; results are ORed. Used to enforce 3DS by amount, guest user, first order, currency, POS list, or trial limits.

Key: `THREE_D_SECURE_RULES`\
Type: array of objects

**Example**

```python
THREE_D_SECURE_RULES = [
    {
        'klass': 'omnishop.orders.rules.amount_limit',
        'defaults': {
            'amount_limit': '1000',
        },
    },
    {
        'klass': 'omnishop.orders.rules.trial_limit_per_user_email',
        'defaults': {
            'user_trial_limit': '2',
            'timeout': 60 * 60,
        },
    },
    {
        'klass': 'omnishop.orders.rules.trial_limit_per_remote_addr',
        'defaults': {
            'remote_addr_trial_limit': '2',
            'timeout': 60 * 60,
        },
    },
]
```

#### **1. Amount Limit Rule**

3D Secure is required when the payment amount is above a given limit.

```json
{
    "klass": "omnishop.orders.rules.amount_limit",
    "defaults": {
        "amount_limit": "1000"
    }
}
```

#### **2. Masterpass Amount Limit Rule**

3D Secure is required when the payment amount with Masterpass is above a given limit.

```json
{
    "klass": "omnishop.orders.rules.masterpass_amount_limit",
    "defaults": {
        "default_amount_limit": "1000",
        "masterpass_amount_limit": 200
    }
}
```

#### **3. Three-D Pos List Rule**

3D Secure is required for payments when the POS slug is in the configured list.

```json
{
    "klass": "omnishop.orders.rules.check_pos_slug_three_d_only",
    "defaults": {
        "three_d_pos_slug_list": ["pos1", "pos2", "pos3"]
    }
}
```

#### **4. Trial Limit per User Rule**

A trial limit per user email is applied within a time window. If the user exceeds the number of trials in that period, 3D Secure is required.

```json
{
    "klass": "omnishop.orders.rules.trial_limit_per_user_email",
    "defaults": {
        "user_trial_limit": "2",
        "timeout": 3600
    }
}
```

`timeout` is in seconds (e.g. 3600 = 1 hour).

#### **5. Trial Limit per IP Address Rule**

A trial limit per remote (IP) address is applied within a time window. If the limit is exceeded, 3D Secure is required.

```json
{
    "klass": "omnishop.orders.rules.trial_limit_per_remote_addr",
    "defaults": {
        "remote_addr_trial_limit": "2",
        "timeout": 3600
    }
}
```

`timeout` is in seconds (e.g. 3600 = 1 hour).

#### **6. Guest User Rule**

Guest (unauthenticated) users are always required to perform 3D Secure.

```json
{
    "klass": "omnishop.orders.rules.only_guest_user",
    "defaults": {}
}
```

#### **7. First Order Rule**

3D Secure is required when the order is the user's first order. For guests, the behaviour depends on `THREE_D_SECURE_ENABLED`. For registered users, if the user has no orders, 3D Secure is required.

```json
{
    "klass": "omnishop.orders.rules.is_first_order",
    "defaults": {}
}
```

#### **8. Payment currency Rule**

3D Secure is required for payments in specific currencies.

```json
{
    "klass": "omnishop.orders.rules.payment_currency",
    "defaults": {
        "currencies": ["try", "eur"]
    }
}
```

**Supported currency codes**

```json
[
    "try", "eur", "usd", "egp", "gbp", "mad", "pln", "sar", "ron", "uah",
    "czk", "huf", "rub", "bgn", "iqd", "kwd", "bhd", "omr", "qar", "aed",
    "ngn", "inr", "lei", "kzt", "jod", "rsd", "amd", "cfa", "lyd"
]
```

### **10. Identity Number Required Amount**

Order total threshold (numeric) above which the shipping address must have an identity number. If set (e.g. 300), checkout validation compares the pre-order total (with interest) to this value; when the total is greater and the selected shipping address has no identity number, a validation error is raised so the user must provide it. Set to `null` or omit to not require identity number by amount.

**Usage:** In `omnishop.orders.serializers.input_serializers` (e.g. address/checkout input validation): `amount_limit = dynamic_settings.IDENTITY_NUMBER_REQUIRED_AMOUNT`; if `amount_limit is not None` and `pre_order.get_total_amount_with_interest() > amount_limit` and the shipping address has no `identity_number`, a `ValidationError` is raised for the identity number field.

Key: `IDENTITY_NUMBER_REQUIRED_AMOUNT`\
Type: number (int/float) or null

**Example:** `300` — require identity number for orders over 300 (in the order currency); `null` — do not enforce by amount.

### **11. Anonymous Address Expire Seconds**

Lifetime in seconds for anonymous users’ session-stored address references. When an anonymous user adds, updates, or deletes an address, the session stores the address hash(es) and an expiry timestamp set to *now + this value*. When reading addresses, the service returns them only if the stored expiry time is still in the future; after that, the addresses are no longer returned (effectively expired). Logged-in users are not affected.

**Usage:** In `omnishop.utils.sessions.AnonymousUserAddressService`: on add/update/delete of anonymous address, `request.session[address_expire_key] = time.time() + dynamic_settings.ANONYMOUS_ADDRESS_EXPIRE_SECONDS`; in `get_anonymous_addresses()`, addresses are returned only when `expire_time and (expire_time > time.time())`.

See [Guest User Lifecycle](https://docs.akinon.com/technical-guides/commerce/guest-user-lifecycle.md) for how this setting fits into the guest checkout flow.

Key: `ANONYMOUS_ADDRESS_EXPIRE_SECONDS`\
Type: number (int)

**Example:** `1800` (30 minutes); default is `60 * 30` if not set in Django settings.

### **12. Offer Show Listing Kwargs**

When `true`, queries that fetch active basket offers (campaigns) for product listing or detail use `select_related` for `promotion`, `condition`, `benefit`, and their `product_collection` relations so that full offer details are loaded in one go. When `false`, those relations are not eagerly loaded, reducing query size and cost but requiring extra queries if listing code needs promotion/condition/benefit data. Use `true` when listing or product APIs need to expose promotion, condition, and benefit information per product.

**Usage:** Read in `omnishop.promotions.models.get_basket_offers_from_cache()`, `omnishop.products.managers` (active offers prefetch), and `omnishop.products.resources.serializers`; when true, the queryset is extended with `.select_related("promotion", "condition", "benefit", "condition__product_collection", "benefit__product_collection")`.

Key: `OFFER_SHOW_LISTING_KWARGS`\
Type: boolean

**Example:** `true` to include full offer details in listing/campaign queries; `false` (default) to avoid extra joins.

### **13. Test User Emails**

List of email addresses that are treated as “test users” for visibility of hidden products. If a product is marked hidden (`is_hidden`), the product detail view allows access only when the request user is authenticated *and* the user’s email is in this list; otherwise the view raises `Http404`. Use this to let internal or test accounts view products that are hidden from normal users.

**Usage:** In `omnishop.products.resources.views` (product detail): when `product.is_hidden`, access is allowed only if `request.user.is_authenticated` and `request.user.email in dj_dynamic_settings.TEST_USER_EMAILS`; otherwise `raise Http404`.

Key: `TEST_USER_EMAILS`\
Type: array (list of strings)

**Example:** `["qa@example.com", "test@test.com"]`. Default: `[]`.

### **14. Product End Of Life Attribute**

Product attribute key (e.g. `end_of_life`) whose value indicates that the product is no longer sold. For a single product: if this attribute is truthy *and* the product has no stock, the product detail view returns `Http404`. For a grouped product: if this attribute is truthy, the view returns `Http404` regardless of stock. Use it to hide discontinued or end-of-life products from the storefront.

**Usage:** In `omnishop.products.resources.views`: on product detail, `eol_attr = dj_dynamic_settings.PRODUCT_END_OF_LIFE_ATTRIBUTE`; if `product.attributes.get(eol_attr)` is truthy and (for single product) `not product.has_any_stock()`, or for grouped product if the attribute is set, the view raises `Http404`. Same attribute is used on grouped product detail view.

Key: `PRODUCT_END_OF_LIFE_ATTRIBUTE`\
Type: string

**Example:** `"end_of_life"` or `"discontinued"` — the product’s attributes dict must contain this key with a truthy value (and no stock for single products) to trigger 404.

### **15. Pass Stock Check on Detail**

When `true`, the product detail page service is called with `pass_stock_check=True`, so the detail can be returned even when the product would normally fail a stock or listability check (e.g. out of stock). When `false`, the usual stock check applies and the detail may not be shown or may redirect if the product is not listable. Use `true` to allow viewing detail for out-of-stock or otherwise non-listable products (e.g. for SEO or “notify me” flows).

**Usage:** In `omnishop.products.resources.views` (product detail): `pass_stock_check = dj_dynamic_settings.PASS_STOCK_CHECK_ON_DETAIL` is passed to `self.service.get_detail_page(..., pass_stock_check=pass_stock_check)`; the service uses it to skip or relax stock checks when building the detail response.

Key: `PASS_STOCK_CHECK_ON_DETAIL`\
Type: boolean

**Example:** `true` to show detail regardless of stock; `false` (default) to enforce stock/listability on detail.

### **16. Category Detail Max Depth**

Maximum category depth at which the category page is shown as a “landing” view (e.g. with subcategory tiles). If the current category’s depth is greater than this value (and `force_landing` is not set), the view switches to a listing/facet view that shows products in that category instead of a deeper landing. So lower values (e.g. 2) make more categories behave as listing pages; higher values allow deeper categories to still show as landing pages with subcategories.

**Usage:** In `omnishop.products.resources.views.CategoryDetailPageView.get()`: `max_depth = dj_dynamic_settings.CATEGORY_DETAIL_MAX_DEPTH`; if `category_node.depth > max(1, max_depth)` and not `force_landing`, a facet view is used (listing); otherwise the category landing is used.

Key: `CATEGORY_DETAIL_MAX_DEPTH`\
Type: number (int)

**Example:** `2` — categories at depth 3 or more show as listing; `3` — only depth 4+ show as listing. Default: `2`.

### **17. Product Stock Out Visibility Enabled**

When `true`, search and listing queries do not filter out out-of-stock products: the base Elasticsearch query uses an “exists” clause on the stock field instead of “stock > 0”, so products with zero stock can appear in results. When `false`, only products with stock > 0 are returned. Also controls what gets indexed: the search indexer includes or excludes out-of-stock products according to this setting. Changing it triggers a post-save action to refresh the index.

**Usage:** In `omnishop.search.utils.get_base_es_query()`: if true, `stock_q = Q("exists", field=stock_field)`; otherwise `stock_q = Q("range", stock_field: {"gt": 0})`. Used in `omnishop.search.services`, `omnishop.search.indexer` for indexing and query building. Has a post\_save\_action to update index (e.g. refresh sitemap/stock visibility).

Key: `PRODUCT_STOCK_OUT_VISIBILITY_ENABLED`\
Type: boolean

**Example:** `true` to show out-of-stock products in search and listing; `false` (default) to hide them.

### **18. Search Default Page Size**

Default number of results per page for search and catalog listing views when the client does not send a page size. Must be at least 1. Used as the default for pagination in search API and category/search result pages.

**Usage:** In `omnishop.search.resources.views`: `default_page_size = property(lambda self: dynamic_settings.SEARCH_DEFAULT_PAGE_SIZE)`; this value is used when building paginated search/catalog responses. Validated with `MinValueValidator(1)` in `omnishop.search.settings.conf`.

Key: `SEARCH_DEFAULT_PAGE_SIZE`\
Type: number (int), minimum 1

**Example:** `20` (default); `12` or `24` for smaller/larger pages.

### **19. Slot Days Count**

Number of days to generate delivery slots for, starting from the first allowed slot date (which is determined by `DEFERRED_SLOT_DAYS_COUNT`). For example, if this is 5 and the first slot day is Wednesday, slots are generated for Wednesday through Sunday. Passed to the slot service as the `days` argument when building the list of selectable delivery time ranges.

**Usage:** In `omnishop.slots.resources.views` and `omnishop.orders.pages.slots`: `slot_days_count = dynamic_settings.SLOT_DAYS_COUNT` is passed to `slot_service.generate_slots(days=slot_days_count, deferred_days=deferred_slot_days_count, ...)` to control how many days of slots are offered.

Key: `SLOT_DAYS_COUNT`\
Type: number (int)

**Example:** `2` — two days of slots; `5` — five days. Default: `2`.

### **20. Deferred Slot Days Count**

Number of days to skip from today before the first available delivery slot day. For example, if today is Monday and this is 2, the first slot day is Wednesday; slots are then generated for the next `SLOT_DAYS_COUNT` days starting from Wednesday. Passed to the slot service as `deferred_days` so that delivery options start from a future date (e.g. to account for preparation or cutoff rules).

**Usage:** In `omnishop.slots.resources.views` and `omnishop.orders.pages.slots`: `deferred_slot_days_count = dynamic_settings.DEFERRED_SLOT_DAYS_COUNT` is passed to `slot_service.generate_slots(..., deferred_days=deferred_slot_days_count, ...)`. Can be combined with `DEFERRED_SLOT_IGNORED_DAYS` for more control.

Key: `DEFERRED_SLOT_DAYS_COUNT`\
Type: number (int)

**Example:** `0` — first slot is today (default); `2` — first slot is in 2 days (e.g. Monday → Wednesday).

### **21. Auth Password Validators**

Defines the list of password validators applied when a user sets or changes their password. Each item is an object with **NAME** (dotted path to a class that extends Django `BasePasswordValidator`) and optional **OPTIONS** (kwargs passed to the validator). The same list is used in registration, password-change forms, and profile/serializer password validation so strength rules (length, capitals, numbers, common passwords, etc.) are applied consistently.

**Where it is used**

* **omnishop.users.forms** — `SetPasswordForm.clean_password2()` and `AllAuthSetPasswordForm.clean_password2()`: `auth_password_validators = dj_dynamic_settings.AUTH_PASSWORD_VALIDATORS`; then `validate_password(password, user=..., password_validators=get_password_validators(auth_password_validators))`.
* **omnishop.users.resources.serializers** — When validating password in user serializers (e.g. registration or profile update): validators are built from this setting and run against the submitted password.

**Allowed validator names (NAME)**\
Built-in choices in `PasswordValidatorSerializer` include: `MinimumLengthValidator`, `CommonPasswordValidator`, `NumericPasswordValidator`, `UserAttributeSimilarityValidator` (Django); `MaximumLengthValidator`, `MinimumCapitalLetterValidator`, `MinimumLowerCaseLetterValidator`, `MinimumLetterValidator`, `MinimumNumberValidator`, `MinimumSpecialCharacterValidator`, `PreviouslyUsedPasswordValidator` (omnicore); `OldPasswordValidator` (omnishop).

Key: `AUTH_PASSWORD_VALIDATORS`\
Type: array of objects (each: `NAME` string, `OPTIONS` object)\
Default: from Django settings `AUTH_PASSWORD_VALIDATORS`

**Example**

```
[
    {"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator", "OPTIONS": {"min_length": 8}},
    {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
    {"NAME": "omnicore.utils.password_validators.MinimumNumberValidator", "OPTIONS": {}}
]
```

### **23. Reset Email Html Template**

Template name (path) used for the **HTML part** of the password reset email sent when a user requests a password reset. If set, Django's `PasswordResetForm.send_mail()` is called with `html_email_template_name` set to this value, so the reset link email can use your custom HTML layout instead of the default.

**Where it is used**

* **omnishop.users.forms.PasswordResetForm** — In `send_mail()`: `kwargs['html_email_template_name'] = dj_dynamic_settings.RESET_EMAIL_HTML_TEMPLATE` before calling `super().send_mail(*args, **kwargs)`. Only has effect if the form sends HTML; the template receives the same context as the plain-text reset email (e.g. user, reset link).

Key: `RESET_EMAIL_HTML_TEMPLATE`\
Type: string (template path)\
Default: `getattr(settings, "RESET_EMAIL_HTML_TEMPLATE", None)` (often `None`)

**Example**

* `"emails/password_reset.html"` — use a project template under `templates/emails/password_reset.html`.
* `None` or unset — no HTML part or Django default behaviour.

### **24. Phone Number Unique Validator Active**

When `true`, the phone number field is validated so that it is unique across active users (no other active user can have the same phone). When `false`, the `UniqueValidator` for phone is not applied and duplicate phone numbers are allowed. Use this to enforce one-phone-per-account in registration and profile updates, or disable it to allow shared/duplicate phones (e.g. family or test data).

**Where it is used**

* **omnishop.users.resources.serializers** — Phone field validators use `ConditionalValidator(lambda: dj_dynamic_settings.PHONE_NUMBER_UNIQUE_VALIDATOR_ACTIVE, UniqueValidator(queryset=User.objects.filter(is_active=True), message=_('Phone number is already in use with another account.')))`. So when the setting is true, the uniqueness check runs; when false, it is skipped. Used on **RegisterSerializer** and any profile/serializer that includes the phone field (e.g. around lines 89, 249, 461).

Key: `PHONE_NUMBER_UNIQUE_VALIDATOR_ACTIVE`\
Type: boolean\
Default: `False`

**Example**

* `true` — registration and profile update will fail if the phone is already used by another active user.
* `false` — duplicate phone numbers are allowed.

### **25. Contact Us Email To**

Maps **operation** (or context) keys to the recipient email address(es) for the Contact Us form. Each value must be a single email string or a list of email strings; all are validated as valid emails. The form submits an **operation** (e.g. `defaults`, `contact_us`, `franchise`); the service looks up `CONTACT_US_EMAIL_TO[operation]` or falls back to `CONTACT_US_EMAIL_TO['defaults']` to build the **To** list for the email. Optional behaviour: `CONTACT_US_SEND_USER` adds the submitter to To; `CONTACT_US_REPLY_TO_ONLY_USER` sets Reply-To to the submitter only.

**Where it is used**

* **omnishop.users.resources.serializers** — In `validate_operation()`: `contact_us_emails = dj_dynamic_settings.CONTACT_US_EMAIL_TO`; the submitted operation must be one of `contact_us_emails.keys()`, otherwise a validation error is raised.
* **omnishop.users.service** — When sending the Contact Us email: `contact_us_emails = dj_dynamic_settings.CONTACT_US_EMAIL_TO`; `to = contact_us_emails.get(operation) or contact_us_emails.get('defaults')`; if `to` is a list/tuple it is used as-is, if a string it is wrapped in a single-element tuple. That `to` is used as the email To list (and optionally combined with the user email per `CONTACT_US_SEND_USER` / `CONTACT_US_REPLY_TO_ONLY_USER`).

Key: `CONTACT_US_EMAIL_TO`\
Type: object (dict: key → string or list of strings, all valid emails)\
Default: `{"defaults": "contactus@akinon.com"}` (or from Django settings)

**Example**

```
{
    "defaults": ["contactus@example.com"],
    "contact_us": "support@example.com",
    "franchise": ["franchise@example.com", "backup@example.com"]
}
```

The **operation** chosen in the form (e.g. `franchise`) selects the value for that key; if the key is missing, `defaults` is used.

### **26. Available Currencies**

List of currency codes that the shop supports (e.g. `["try", "usd", "eur"]`). Validation rules: the list must contain no duplicates and must include the value of `DEFAULT_CURRENCY`. Used to validate user-selected currency (e.g. in serializers) and to expose which currencies the frontend can offer in the API.

**Where it is used**

* **omnishop.users.settings.conf** — `AvailableCurrencies` validators ensure `len(currencies) == len(set(currencies))` and `dynamic_settings.DEFAULT_CURRENCY in currencies`.
* **omnishop.users.resources.serializers** — Currency choice validation checks that the value is in `dj_dynamic_settings.AVAILABLE_CURRENCIES` (e.g. `lambda currency_code: (currency_code in dj_dynamic_settings.AVAILABLE_CURRENCIES)`).
* **omnishop.utils.currency** — Asserts that the currency is in `dynamic_settings.AVAILABLE_CURRENCIES`.
* **omnishop.users.resources.views** — Response includes `"available_currencies": dynamic_settings.AVAILABLE_CURRENCIES` for the client.

Key: `AVAILABLE_CURRENCIES`\
Type: array (list of strings; choices from `CurrencyType.choices()`)\
Default: `[settings.DEFAULT_CURRENCY_TYPE]`

**Example**

```json
["try", "usd", "eur"]
```

Must include the value of `DEFAULT_CURRENCY` (e.g. if default is `try`, `try` must be in the list).

### **27. User Phone Regex**

Regular expression used to validate user phone numbers (format and length). Applied in validators, services, and allauth adapter; also exposed in the API so the frontend can show the expected format or run client-side validation. Some code strips the leading `^` for use in DB or display patterns.

**Where it is used**

* **omnishop.users.validators** — `regex = dynamic_settings.USER_PHONE_REGEX`; used to validate phone input.
* **omnishop.users.service** — `regex = dynamic_settings.USER_PHONE_REGEX.replace("^", "")` for formatting/validation logic.
* **omnishop.users.allauth\_adapter** — Same regex (with `^` stripped) for phone handling.
* **omnishop.users.resources.views** — Response includes `"user_phone_regex": dynamic_settings.USER_PHONE_REGEX` for the client.

Key: `USER_PHONE_REGEX`\
Type: string\
Default: `r'^(05)\d{9}$'` (Turkish mobile: 05 + 9 digits)

**Example**

* `^(05)\d{9}$` — Turkish mobile (05xxxxxxxxx).
* `^(09)\d{9}$` — Alternative 09-prefix format.
* `^\+90\d{10}$` — E.164-style Turkish.

### **28. User Phone Format**

Example phone string displayed in validation error messages so the user sees the expected format (e.g. placeholder or hint). Human-readable only; actual validation is done with `USER_PHONE_REGEX`. Use a value that matches your regex (e.g. same length and pattern).

**Where it is used**

* Used where phone validation errors are raised so the message can include this format (e.g. "Phone must match format: {USER\_PHONE\_FORMAT}").
* Default ensures a sensible Turkish-style example when the setting is not overridden.

Key: `USER_PHONE_FORMAT`\
Type: string\
Default: `"05999999999"`

**Example**

* `05999999999` — Turkish mobile placeholder.
* `05123456789` — Alternative example matching the same regex.

> **Note (email):** There is no email equivalent of `USER_PHONE_REGEX` / `USER_PHONE_FORMAT`. The user `email` field uses standard syntax validation only, is stored with its original casing, and is not normalized or format‑constrained by any dynamic setting. See [User Email Validation & Normalization](https://docs.akinon.com/technical-guides/commerce/user-email-validation-and-normalization.md).

### **29. Active Subscription Gateways**

List of subscription gateway **names** (strings) that are currently active. Resolution order in `get_subscription_gateways()`: (1) if CMS gateways of type subscription exist, those are used; (2) else if this list is non-empty, this list is returned; (3) else `[SUBSCRIPTION_GATEWAY]` is returned. Each name in this list must exist as a key in `SUBSCRIPTION_GATEWAYS` so that `get_gateway_settings(gateway_name)` can load `klass` and `conf`. Use multiple names to run several gateways (e.g. Emarsys + Insider); use an empty list to rely on the single `SUBSCRIPTION_GATEWAY`.

**Where it is used**

* **omnishop.users.service** — In `get_subscription_gateways()`: `active_subscription_gateways = dj_dynamic_settings.ACTIVE_SUBSCRIPTION_GATEWAYS`; if `active_subscription_gateways` is truthy, the method returns it; otherwise returns `[subscription_gateway]`. The returned names are then used to instantiate gateways via `get_gateway_settings(name)` and `get_subscription_gateway(name)`.

Key: `ACTIVE_SUBSCRIPTION_GATEWAYS`\
Type: array (list of strings)\
Default: `getattr(settings, "ACTIVE_SUBSCRIPTION_GATEWAYS", [])`

**Example**

```json
["emarsys", "insider"]
```

* Two gateways active; both must have entries in `SUBSCRIPTION_GATEWAYS`.
* `[]` — no active list; `SUBSCRIPTION_GATEWAY` is used as the single gateway.

### **30. Subscription Gateway**

Single subscription gateway **name** used when `ACTIVE_SUBSCRIPTION_GATEWAYS` is empty. Must match a key in `SUBSCRIPTION_GATEWAYS`. The subscription service calls `get_gateway_settings(this_name)` to get the config dict (from DB or from `SUBSCRIPTION_GATEWAYS[name]`), then instantiates the gateway with `klass` and `conf`. Typical values are gateway slugs such as `emarsys`, `insider`, `revotas`, `setrow`, `euromessage`.

**Where it is used**

* **omnishop.users.service** — In `get_subscription_gateways()`: `subscription_gateway = dj_dynamic_settings.SUBSCRIPTION_GATEWAY`; when `ACTIVE_SUBSCRIPTION_GATEWAYS` is empty, the method returns `[subscription_gateway]`. That name is later passed to `get_gateway_settings(gateway_name)` which does `dj_dynamic_settings.SUBSCRIPTION_GATEWAYS.get(gateway_name, None)` if not found in CMS Gateway model.

Key: `SUBSCRIPTION_GATEWAY`\
Type: string\
Default: `getattr(settings, "SUBSCRIPTION_GATEWAY", None)`

**Example**

* `emarsys` — use the `emarsys` entry in `SUBSCRIPTION_GATEWAYS`.
* `revotas` — use Revotas gateway config.
* `insider` — use Insider gateway config.

The value must exist as a key in `SUBSCRIPTION_GATEWAYS` (or be provided by CMS Gateway settings).

### **31. Subscription Active**

Master switch for subscription/membership features (newsletter, CRM sync, consent gateways). When `false`, subscription-related views or logic may be skipped (e.g. the decorated view does nothing, or the post-login sync is not triggered). When `true`, subscription gateways and sign-up flows operate as configured; the receiver can trigger `subscribe_user_pk_task` after user login.

**Where it is used**

* **omnishop.utils.decorators.subscription\_activated** — Wraps a view so it runs only when `dynamic_settings.SUBSCRIPTION_ACTIVE` is true: `if dynamic_settings.SUBSCRIPTION_ACTIVE: return fn(self, *args, **kwargs)`; otherwise the wrapped function is not called.
* **omnishop.users.receivers.user\_subscription\_receiver\_on\_save** — On user save (not create) when `instance.last_login` is set: `if dynamic_settings.SUBSCRIPTION_ACTIVE and not created and instance.last_login:` then `subscribe_user_pk_task.delay(instance.pk)` is enqueued to sync the user with subscription gateways.

Key: `SUBSCRIPTION_ACTIVE`\
Type: boolean\
Default: `getattr(settings, "SUBSCRIPTION_ACTIVE", False)`

**Example**

* `true` — subscription views and post-login subscription sync are active.
* `false` — subscription flows are disabled (default).

### **32. Favourite SKU is Active**

Controls which product identifier is used when listing or deduplicating favourite (wishlist) products. When `true`, the favourite list is distinct by `product_id` (one row per product ID). When `false`, it is distinct by `product__base_code` (one row per base code, so variants can be grouped). Affects both the `order_by`/`distinct()` clause and the meaning of "same product" in the favourites list.

**Where it is used**

* **omnishop.wishlists.resources.views.FavouriteProductViewSet.list** — `favourite_sku_is_active = dynamic_settings.FAVOURITE_SKU_IS_ACTIVE`; then `distinct_query = 'product_id' if favourite_sku_is_active else 'product__base_code'`; the queryset is ordered and distinct by that field so the list shows one entry per product ID or per base code.

Key: `FAVOURITE_SKU_IS_ACTIVE`\
Type: boolean\
Default: from Django settings

**Example**

* `true` — favourites are keyed by `product_id` (each variant counts separately).
* `false` — favourites are keyed by `base_code` (variants of the same base product grouped).

### **33. Max Product per User Collection**

Maximum number of products allowed in a single user collection (e.g. a wishlist or custom list). When the user adds an item, the serializer counts existing items in that collection; if `total_products >= MAX_PRODUCT_PER_USER_COLLECTION`, a validation error is raised and the add is rejected. The error message can include the limit (e.g. "You can not add more than {0} products to collection.").

**Where it is used**

* **omnishop.wishlists.serializers.UserCollectionItemSerializer.validate** — `user_collection_max_product = dynamic_settings.MAX_PRODUCT_PER_USER_COLLECTION`; `total_products = self.Meta.model.objects.filter(usercollection=attrs['usercollection']).count()`; if `total_products >= user_collection_max_product` then `ValidationError` is raised with the configured message.

Key: `MAX_PRODUCT_PER_USER_COLLECTION`\
Type: number (int)\
Default: from Django settings (often 50 in comments)

**Example**

* `50` — up to 50 products per collection.
* `100` — more per list. Use a lower value (e.g. `2`) in tests to assert the limit.

### **34. AddressPhoneMinLength**

Minimum number of characters required for the address phone number in the Address serializer. The phone field is validated with Django's `MinLengthValidator(ADDRESS_PHONE_MIN_LENGTH)`; values shorter than this are rejected. Use it to enforce a minimum length (e.g. 11 for Turkish mobile) without tying to a specific regex.

**Where it is used**

* **omnishop.address.resources.serializers** — The address phone field has a validator: `MinLengthValidator(dynamic_settings.ADDRESS_PHONE_MIN_LENGTH)(value)` (or equivalent via `lambda value: MinLengthValidator(dynamic_settings.ADDRESS_PHONE_MIN_LENGTH)(value)`). Applied when validating address data (e.g. checkout or profile address).

Key: `ADDRESS_PHONE_MIN_LENGTH`\
Type: number (int)\
Default: 11

**Example**

* `11` — Turkish mobile length (05xxxxxxxxx).
* `10` — Shorter format. Should be consistent with `USER_PHONE_REGEX` if both are used.

### **35. CheckoutWithTokenAllowAnonymous**

When `true`, anonymous users can open the checkout-with-token flow (e.g. from a QR code or one-time link): the view allows access when there is no user from the token but the session exists and this setting is true. When `false`, token checkout requires an authenticated user from the token; otherwise 404 or "not allowed" is returned. Also controls whether checkout URLs with token are generated for anonymous sessions (e.g. in-store flow).

**Where it is used**

* **omnishop.orders.views.CheckoutWithTokenView\.get** — `anonymous_allowed = dynamic_settings.CHECKOUT_WITH_TOKEN_ALLOW_ANONYMOUS`; if `not user and (not anonymous_allowed or not getattr(request.session, "session_key", None))` then `raise Http404`. So anonymous access is allowed only when this is true and a session exists.
* **omnishop.orders.service** — In `get_checkout_urls_with_token`: `is_anonymous_allowed = dj_dynamic_settings.CHECKOUT_WITH_TOKEN_ALLOW_ANONYMOUS`; `_is_user_allowed(request, is_anonymous_allowed)` decides whether to return checkout URL and token; the query string is built with `is_anonymous_allowed` so the frontend can show the right behaviour.

See [Guest User Lifecycle](https://docs.akinon.com/technical-guides/commerce/guest-user-lifecycle.md) for how this setting fits into the guest checkout flow.

Key: `CHECKOUT_WITH_TOKEN_ALLOW_ANONYMOUS`\
Type: boolean\
Default: false

**Example**

* `true` — QR/one-time-link checkout works for guest users (with session).
* `false` — only logged-in user from token can use the link (default).

### **36. OrdersRefundableDays**

Number of days after order (or order item) placement during which the order is eligible for return/refund. Exposed as a property on the order and on order items so refund/return logic can decide whether to allow the action. Past this window, return or refund options are typically disabled. `null` means no day-based limit is enforced by this setting (downstream logic may still allow or deny).

**Where it is used**

* **omnishop.orders.models.Order.refundable\_days** — `return dynamic_settings.ORDERS_REFUNDABLE_DAYS`.
* **omnishop.orders.models.OrderItem.refundable\_days** — `return dynamic_settings.ORDERS_REFUNDABLE_DAYS`. Refund/return code compares order age (e.g. days since creation) to this value to decide eligibility.

Key: `ORDERS_REFUNDABLE_DAYS`\
Type: number (int) or null\
Default: `getattr(settings, "ORDERS_REFUNDABLE_DAYS", None)`

**Example**

* `30` — returns/refunds allowed within 30 days of order.
* `14` — shorter window.
* `null` — no day limit from this setting; business logic may still restrict returns.

The countdown starts from the date field selected by `ORDERS_REFUNDABLE_START_DATE_FIELD`. See **147. OrdersRefundableStartDateField**.

> **Note:** The product attribute `is_refundable` takes precedence over this setting. When a product carries `is_refundable` as false, its items are never refundable and no date calculation runs. Products without the attribute are treated as refundable.

### **37. GiftBoxConfigurations**

Config for the optional gift-box product in checkout: **sku** — product SKU used to resolve the gift box product and its price; **is\_active** — boolean to show/hide the gift box step and offer. When `is_active` is true, the checkout index page and gift box page use this config; the `GiftBox` helper is instantiated with `**dj_dynamic_settings.GIFT_BOX_CONFIGURATIONS` so it can load price and attach the gift box to the pre\_order.

**Where it is used**

* **omnishop.orders.pages.index** — `gift_box_conf = dj_dynamic_settings.GIFT_BOX_CONFIGURATIONS`; context includes `'has_gift_box': gift_box_conf.get('is_active') or False`.
* **omnishop.orders.pages.gift\_box** — `GiftBoxPreCondition.is_valid` and `GiftBoxPage.is_gift_box_active` use `gift_box_conf.get('is_active')`. `GiftBoxPage.get_page_context` and `process_pre_order` build a `GiftBox` with `GiftBox(..., **dj_dynamic_settings.GIFT_BOX_CONFIGURATIONS)` to get price and attach to pre\_order.

Key: `GIFT_BOX_CONFIGURATIONS`\
Type: object (keys: `sku`, `is_active`)\
Default: `{"sku": null, "is_active": false}`

**Example**

```json
{"sku": "GIFT-BOX-01", "is_active": true}
```

* `sku` must match a product SKU in the catalog; that product is used as the gift box and for pricing.

### **38. PrettyUrlIncludeDefaultLanguage**

When `true`, pretty URL generation includes the default/site language in the path even when the language is the default (e.g. `/en/products/...` for default English). When `false`, the default language is represented with a "none" language code so the path can omit the language prefix (e.g. `/products/...` for default). Used inside the prettyurls language decorator when building `language_code` for URL generation.

**Where it is used**

* **omnishop.prettyurls.generators** — In the decorator that injects language into URL generation: `include_default_language = dynamic_settings.PRETTY_URL_INCLUDE_DEFAULT_LANGUAGE`; if `language == site_language and not include_default_language` then `language_code = none_language`, else `language_code = get_language_prefix(language).lower()`. So the generated path includes or omits the language segment based on this setting.

Key: `PRETTY_URL_INCLUDE_DEFAULT_LANGUAGE`\
Type: boolean\
Default: false

**Example**

* `true` — default language still appears in URL (e.g. `/en/...`).
* `false` — default language has no prefix in the path (e.g. `/...`).

### **39. ForceNotRedirectForI18N**

When `true`, the I18N middleware skips the logic that redirects the user to a URL with the correct language prefix (e.g. when `PRETTY_URL_MULTI_LANGUAGE` is true and the path language does not match the active language or site default). When `false`, that redirect runs so users are sent to the localized path. Use `true` to disable automatic language redirects (e.g. for API or when you handle language elsewhere).

**Where it is used**

* **omnicore.utils.middleware** — The condition for performing the language redirect is `getattr(settings, 'PRETTY_URL_MULTI_LANGUAGE', False) and not getattr(dynamic_settings, 'FORCE_NOT_REDIRECT_FOR_I18N', False)`. So when `FORCE_NOT_REDIRECT_FOR_I18N` is true, the block that calls `get_localized_url` and `redirect_response` is skipped and no redirect is made.

Key: `FORCE_NOT_REDIRECT_FOR_I18N`\
Type: boolean\
Default: false

**Example**

* `true` — no automatic redirect to language-prefixed URL.
* `false` — middleware may redirect to the localized URL when multi-language pretty URLs are enabled.

### **40. RetailStoreFilterStrategy**

Dotted path to the strategy class that filters which retail stores (e.g. click-and-collect) are shown for a basket. Strategies: **FullySatisfiedQuantityFilterStrategy** — only stores that can fulfill the full basket quantity; **PartiallySatisfiedQuantityFilterStrategy** — stores that can fulfill at least part; **NotSatisfiedQuantityFilterStrategy** — all stores regardless of stock.

**Where it is used**

* **omnishop.products.backend.gateways.service** — In `get_strategy()`: `klass = import_string(dynamic_settings.RETAIL_STORE_FILTER_STRATEGY)()`; the returned strategy instance is used when resolving store list for the basket (e.g. for pickup or click-and-collect).

Key: `RETAIL_STORE_FILTER_STRATEGY`\
Type: string (dotted path)\
Default: `NotSatisfiedQuantityFilterStrategy`

**Choices**

* `omnishop.products.backend.gateways.filter_strategies.FullySatisfiedQuantityFilterStrategy` — only stores that fully satisfy basket quantity.
* `omnishop.products.backend.gateways.filter_strategies.PartiallySatisfiedQuantityFilterStrategy` — stores that partially satisfy.
* `omnishop.products.backend.gateways.filter_strategies.NotSatisfiedQuantityFilterStrategy` — all stores (no stock filter).

**Example**

Use `FullySatisfiedQuantityFilterStrategy` to show only stores that can fulfill the entire basket; use `NotSatisfiedQuantityFilterStrategy` to show all stores regardless of stock.

### **41. PromotionGatewayActiveSettings**

When `true`, the promotion gateway is considered active and virtual offers (e.g. from brand-specific integrations like Ayakkabı Dünyası) can be queried and applied. When `false`, the gateway is off and no external promotion queries run.

**Where it is used**

* **omnishop.promotions.backend.gateways.service** — In the gateway service: `is_active` is `True` only when `dynamic_settings.PROMOTION_GATEWAY_ACTIVE` and `self.promotion_gateways` are both truthy; `query()` returns an empty list if `not self.is_active`, otherwise it fetches offers from configured promotion gateways.

Key: `PROMOTION_GATEWAY_ACTIVE`\
Type: boolean\
Default: false

**Example**

Set to `True` when using a promotion gateway (e.g. Erencard, Softtouch, Hitit); leave `False` if you do not use external promotion gateways.

### **42. SmsGateways**

Dictionary mapping SMS gateway names to their configuration objects. Each entry typically has `klass` (dotted path to the backend class) and `conf` (gateway-specific options, e.g. `verify_message` for OTP text). The gateway actually used is selected by `SMS_GATEWAY`. Used for sending SMS (OTP, notifications).

**Where it is used**

* **omnishop.orders.service.SmsService** — `_get_sms_gateway_settings(sms_gateway)` returns `dj_dynamic_settings.SMS_GATEWAYS.get(sms_gateway)`; `_get_gateway()` uses that config to instantiate the backend via `import_string(gateway_config.get('klass'))(**gateway_config.get('conf'))`. When `SMS_GATEWAY` is `"console"`, a built-in console backend is used instead.

Key: `SMS_GATEWAYS`\
Type: object\
Default: `{"console": {"conf": {"verify_message": "Verification code: {}"}}}`

**Example**

```json
{
  "console": {"conf": {"verify_message": "Verification code: {}"}},
  "provider_slug": {"klass": "omnishop.orders.backends.SomeSmsBackend", "conf": {"api_key": "..."}}
}
```

### **43. SmsGateway**

Name of the active SMS gateway. If set to `"console"`, SMS/OTP are logged to the console (no real sending). Otherwise this value must exist as a key in `SMS_GATEWAYS`; that entry's `klass` and `conf` are used to send SMS.

**Where it is used**

* **omnishop.orders.service.SmsService** — `_get_gateway()` reads `dj_dynamic_settings.SMS_GATEWAY`; when it is `"console"` it returns `SmsBackend`; otherwise it looks up the config in `SMS_GATEWAYS` and instantiates the configured backend. Used by `send_sms`, `send_otp`, and `verify_otp`.

Key: `SMS_GATEWAY`\
Type: string\
Default: "console"

**Example**

Use `"console"` for local/testing; use the same slug as a key in `SMS_GATEWAYS` (e.g. `"provider_slug"`) for production SMS.

### **44. ReCaptchaSiteKey**

Google reCAPTCHA v2 site key (public key) shown in the browser. The frontend uses it to render the reCAPTCHA widget; the user response token is then verified on the server using `RECAPTCHA_SECRET_KEY`.

**Where it is used**

* **omnishop.users.forms.CaptchaField** — `site_key = property(lambda self: dj_dynamic_settings.RECAPTCHA_SITE_KEY)`; passed to the widget as `data-sitekey`. Both `RECAPTCHA_SITE_KEY` and `RECAPTCHA_SECRET_KEY` must be set or the field raises `ImproperlyConfigured`.

Key: `RECAPTCHA_SITE_KEY`\
Type: string\
Default: ''

**Example**

Set to the site key from Google reCAPTCHA admin (e.g. `"6Lc..."`) when using reCAPTCHA on registration or contact forms.

**See also:** to have the API itself require a reCAPTCHA token on registration and OTP code requests, enable it with `REGISTER_FORM_RECAPTCHA_CONF` (section 156).

### **45. ReCaptchaSecretKey**

Google reCAPTCHA secret key used for server-side verification. The backend sends this with the user's response token to `https://www.google.com/recaptcha/api/siteverify` to validate the captcha.

**Where it is used**

* **omnishop.users.forms.CaptchaField** — `secret_key` property and `validate()`: POST to siteverify with `secret` and `response`; both keys must be defined for the field to work.

Key: `RECAPTCHA_SECRET_KEY`\
Type: string\
Default: ''

**Example**

Set to the secret key from the same reCAPTCHA admin; keep it server-side only and never expose it in the frontend.

**See also:** `REGISTER_FORM_RECAPTCHA_CONF` (section 156) and the `recaptcha_required` option of `VERIFICATION_TOKEN_CONF` (section 142) use this key to verify the `g-recaptcha-response` tokens sent to the API. `REGISTER_FORM_RECAPTCHA_CONF` cannot be enabled while this key is empty. Emptying the key later is not blocked, though: while a reCAPTCHA check is on, every request that needs a token is then rejected as a failed reCAPTCHA.

### **46. SelfAnonymizationEnabled**

When `true`, authenticated users can trigger self-anonymization (account data anonymized and session logged out). When `false`, the self-anonymization API returns 403.

**Where it is used**

* **omnishop.users.views** — In the self-anonymization `patch` handler: `if not dynamic_settings.SELF_ANONYMIZATION_ENABLED` then `raise PermissionDenied()`; otherwise the service anonymizes the user and logs them out.

Key: `SELF_ANONYMIZATION_ENABLED`\
Type: boolean\
Default: false

**Example**

Enable when you offer a "Delete my data" or "Anonymize my account" self-service option; disable if only admins should perform anonymization.

### **47. ContactUsSendUser**

When `true`, the Contact Us form submitter's email is added to the email's **To** list (in addition to `CONTACT_US_EMAIL_TO`). When `false`, only the configured recipients receive the email.

**Where it is used**

* **omnishop.users.service** — When sending the Contact Us email: `if dj_dynamic_settings.CONTACT_US_SEND_USER and email:` then `to += (email,)`. Reply-To is set separately by `CONTACT_US_REPLY_TO_ONLY_USER`.

Key: `CONTACT_US_SEND_USER`\
Type: boolean\
Default: false

**Example**

Set to `true` so the user gets a copy of the message or is visible as a recipient; set to `false` to send only to internal addresses.

### **48. ContactUsReplyToOnlyUser**

When `true`, the Contact Us email's **Reply-To** is set only to the submitter's email so that "Reply" goes to the user. When `false`, Reply-To is the same as the To list.

**Where it is used**

* **omnishop.users.service** — When building the email: `if dj_dynamic_settings.CONTACT_US_REPLY_TO_ONLY_USER and email:` then `reply_to = (email,)`; otherwise `reply_to = tuple(to)`.

Key: `CONTACT_US_REPLY_TO_ONLY_USER`\
Type: boolean\
Default: false

### **49. KvkkGateway**

Configuration for the KVKK (GDPR) consent gateway. When set, the system can sync consent/permission changes (SMS, email, call, ETK share) to an external gateway for verified users. Structure is validated by `KvkkGatewaySerializer` (typically `name` and `conf` or similar fields).

**Where it is used**

* **omnishop.users.service** — In `update_kvkk_permissions()`: `KVKK_GATEWAY = dj_dynamic_settings.KVKK_GATEWAY`; if `not KVKK_GATEWAY or not verified_user` the method returns without calling the gateway; otherwise it calls `update_permissions()` with the gateway (e.g. for Mobildev).

Key: `KVKK_GATEWAY`\
Type: object\
Default: null

**Example**

Configure when using a KVKK/consent provider (e.g. Mobildev); leave null if you do not sync consent to an external gateway.

### **50. DefaultCurrency**

Default currency code for the shop (e.g. `try`, `usd`). Must be one of the values in `AVAILABLE_CURRENCIES`. Used for pricing, basket, and order defaults when no other currency is selected.

**Where it is used**

* **omnishop.users.settings.conf** — Validated via `FunctionThroughValidator`: value must be in `dynamic_settings.AVAILABLE_CURRENCIES`. `AVAILABLE_CURRENCIES` in turn validates that it contains `DEFAULT_CURRENCY`.
* **Orders, promotions, wishlists, segmentation, loyalty** — Tests and services use it as the default currency (e.g. `override_dynamic_settings(DEFAULT_CURRENCY="try")`, basket/order currency fallback).

Key: `DEFAULT_CURRENCY`\
Type: string\
Default: from Django settings (e.g. `DEFAULT_CURRENCY_TYPE`)

**Example**

Set to the primary store currency (e.g. `"try"`, `"usd"`); must appear in `AVAILABLE_CURRENCIES`.

### **51. MobildevConf**

Mobildev integration configuration (validated by `MobildevConfSerializer`). Typically holds a `conf` object with credentials and options used to communicate with the Mobildev API for KVKK/consent, user sync, or subscription features.

**Where it is used**

* **omnishop.libs.kvkk\_gateways.mobildev.service.MobilDevService** — `gateway` property builds the Mobildev gateway with `MobilDev(**settings.MOBILDEV_CONF['conf'])`; used for sending confirmation codes, blacklist, and permission sync.
* **omnishop.users.tests.test\_tasks** — KVKK tasks may override with Mobildev config for testing.

Key: `MOBILDEV_CONF`\
Type: object\
Default: `{}` (from Django `MOBILDEV_CONF`)

**Example**

Configure when using Mobildev for KVKK/consent or user sync; structure must match `MobildevConfSerializer` (e.g. `conf` with API credentials).

### **52. ShouldSendVerificationEmail**

When `true`, the system sends a verification email after guest user registration (and when applicable after order). When `false`, `EMAIL_VERIFICATION` is forced to `None` so no verification email is sent.

**Where it is used**

* **omnishop.users.service** — When creating a guest user: `should_send_mail = dj_dynamic_settings.SHOULD_SEND_VERIFICATION_EMAIL`; if not set, `email_verification` is set to `None` so allauth does not send the verification email.

See [Guest User Lifecycle](https://docs.akinon.com/technical-guides/commerce/guest-user-lifecycle.md) for how this setting fits into the guest checkout flow.

Key: `SHOULD_SEND_VERIFICATION_EMAIL`\
Type: boolean\
Default: true

**Example**

Set to `false` to disable verification emails for guest signups; set to `true` for normal verification flow.

### **53. UniqueValidatorPhoneMessage**

Error message shown when phone uniqueness validation fails (e.g. user or loyalty card registration with a phone number that already exists).

**Where it is used**

* **omnishop.users.resources.serializers** — Raised as `serializers.ValidationError(_(dj_dynamic_settings.UNIQUE_VALIDATOR_PHONE_MESSAGE))` when phone is duplicate (e.g. in user profile, registration, or loyalty serializers).
* **omnishop.loyaltycard.resources.serializers** — Same message when phone uniqueness fails for loyalty card.

Key: `UNIQUE_VALIDATOR_PHONE_MESSAGE`\
Type: string\
Default: `""`

**Example**

e.g. `"This phone number is already registered."` or a localized message key.

### **53.1. User Profile Validations**

Dynamically defines business rule validators that run during user registration and profile updates. When left empty, no additional validation is applied.

Key: `USER_PROFILE_VALIDATIONS`\
Type: array of objects\
Validation: Each element must have a `klass` and optionally a `defaults` field\
Default: `[]`

**Valid `klass` options:**

| Value                                       | Business Rule                                                                                                                                                                                                                                              |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `omnishop.users.helpers.check_orders`       | Blocks profile changes when the user has pending/awaiting-confirmation orders. Prevents critical profile data from changing during payment flows. Use **defaults.status** to restrict to a specific order status (e.g. `"350"` for confirmation\_waiting). |
| `omnishop.users.helpers.check_unique_phone` | Prevents the same phone number from being used on multiple accounts.                                                                                                                                                                                       |

**Element structure:**

| Field      | Type              | Required | Description                                   |
| ---------- | ----------------- | -------- | --------------------------------------------- |
| `klass`    | `string` (choice) | Yes      | Validator to execute                          |
| `defaults` | `dict`            | No       | Additional parameters passed to the validator |

**Important behaviour:**

* Validators run only during **profile updates**, not during registration (registration validations are managed by a separate setting)
* When validation fails, an error is returned to the user and the operation is not completed
* For `check_orders`, the `defaults.status` field is **required**; omitting it will cause a system error

#### **Order status codes**

When using `check_orders`, the **defaults.status** value refers to one of the following order statuses:

| Code | Enum name              | Description                    |
| ---- | ---------------------- | ------------------------------ |
| 50   | cancellation\_waiting  | Cancellation waiting           |
| 100  | cancelled              | Cancelled                      |
| 200  | waiting                | Waiting                        |
| 300  | payment\_waiting       | Payment waiting                |
| 350  | confirmation\_waiting  | Confirmation waiting           |
| 400  | approved               | Approved                       |
| 450  | preparing              | Preparing                      |
| 500  | shipped                | Shipped                        |
| 510  | shipped\_and\_informed | Shipped and informed           |
| 520  | ready\_for\_pickup     | Ready for pickup               |
| 540  | attempted\_delivery    | Attempted delivery             |
| 544  | review\_started        | Review started                 |
| 545  | review\_waiting        | Review waiting                 |
| 546  | waiting\_for\_payment  | Waiting for payment (trade-in) |
| 547  | paid                   | Paid (trade-in)                |
| 550  | delivered              | Delivered                      |
| 600  | refunded               | Refunded                       |

**Example:**

```json
[
  {
    "klass": "omnishop.users.helpers.check_unique_phone",
    "defaults": {}
  },
  {
    "klass": "omnishop.users.helpers.check_orders",
    "defaults": {
      "status": "350"
    }
  }
]
```

In the example above, `check_orders` with `"status": "350"` validates against orders that are in **confirmation\_waiting** status.

### **54. AddressSerializerField**

Per-country configuration for extra or customized fields on the address serializer. Structure: dict keyed by country code (e.g. `"tr"`, `"default"`), each value a list of field configs with `field`, optional `kwargs`, and optional `validators` (klass + kwargs). Used to add or override address fields and validators by country.

**Where it is used**

* **omnishop.address.resources.serializers.AddressSerializer** — In `__init__`: reads `dynamic_settings.ADDRESS_SERIALIZER_FIELDS`; selects the list by `country.code` or falls back to `"default"`; for each entry adds or updates the field (with optional validators). Also respects `ADDRESS_DISTRICT_REQUIRED` for district.

**How `kwargs` is applied**

* Model fields of the serializer (e.g. `district`, `tax_no`, `line`): all `kwargs` apply (e.g. `required`, `max_length`).
* Fields declared on the serializer (`phone_number`, `identity_number`, `address_type`): only `required`, `allow_null`, and `allow_blank` apply; other keys have no effect. Before COMM-4031 these three keys were ignored too, so a config that set them had no effect until that release.
* A field name that does not exist becomes an extra field: a string field that is required unless `kwargs` contains `"required": false`, stored in `extra_field`.
* Validators are added in all three cases. They do not run when the field is missing or `null`, so use `required` / `allow_null` to make a field mandatory.

Key: `ADDRESS_SERIALIZER_FIELDS`\
Type: object (dict: country code to list of field configs)\
Default: `{"default": []}`

**Example**

`{"default": [], "tr": [{"field": "district", "kwargs": {"required": true}, "validators": [{"klass": "...", "kwargs": {"message": "..."}}]}]}`

Mandatory 11-digit identity number for all countries:

`{"default": [{"field": "identity_number", "kwargs": {"required": true, "allow_null": false, "allow_blank": false}, "validators": [{"klass": "django.core.validators.RegexValidator", "kwargs": {"regex": "^\\d{11}$", "message": "Identity number must be 11 digits."}}]}]}`

### **55. TmpSapCRMMobildevActivationSetting**

When `true`, enables temporary logic that uses Mobildev user data (e.g. `mobildev_id` from user attributes) in SAP/Hana CRM flows. When `false`, that behaviour is disabled.

**Where it is used**

* **omnishop.libs.crm\_gateways.hana.service** — When syncing or building CRM payloads: `if getattr(dynamic_settings, "TMP_SAP_CRM_MOBILDEV_ACTIVATION_SETTING", False):` then e.g. `mobildev_id = user.attributes.get("mobildev_id")` is used.
* **omnishop.libs.crm\_gateways.hana.gateway** — Same check for Mobildev activation in gateway code.

Key: `TMP_SAP_CRM_MOBILDEV_ACTIVATION_SETTING`\
Type: boolean\
Default: false

**Example**

Set to `true` only when SAP CRM integration is configured to use Mobildev IDs; treat as temporary until a permanent integration is in place.

### **56. CRMConf**

CRM integration configuration. Typically a dict with a `conf` key holding gateway-specific options (e.g. SAP/Hana CRM credentials and endpoints). Used when syncing orders or customers to an external CRM.

**Where it is used**

* **omnishop.libs.crm\_gateways.hana.service** — Gateway is built with `HanaCrmGateway(**dynamic_settings.CRM_CONF['conf'])`; used for order/customer sync to Hana CRM.

Key: `CRM_CONF`\
Type: object\
Default: `{}` (from Django `CRM_CONF`)

**Example**

Structure must match what the CRM gateway expects (e.g. `{"conf": {"base_url": "...", ...}}` for Hana).

### **57. OmnitronAPI**

Omnitron API credentials and endpoints (validated by `OmnitronAPISerializer`). Used by the Omnitron API client for auth, orders, cancellation, shipping cost, etc.

**Where it is used**

* **omnishop.libs.api\_clients.omnitron.client.OmnitronApiClient** — `get_data()` reads `getattr(dynamic_settings, 'OMNITRON_API', {})` for `host`, `oms_host`, `auth_url` (derived from host), `username`, `passwd`, `email`, `channel_id`. Used for authentication and all API requests (orders, cancellation, bank account, etc.).
* **omnishop.orders.service**, **omnishop.orders.resources.views**, **omnishop.orders.pages.base**, **omnishop.orders.tasks** — Use `OmnitronApiClient()` which relies on this setting.

Key: `OMNITRON_API`\
Type: object\
Default: `{}` (from Django `OMNITRON_API`)

**Example**

e.g. `{"host": "https://...", "username": "...", "passwd": "...", "email": "..."}`; may include `oms_host`, `channel_id` depending on serializer.

### **58. SecuritycopIpBanTimeout**

Duration in seconds that an IP ban lasts (e.g. after too many failed login or suspicious attempts). After this time, the IP is no longer treated as banned and the cache key expires.

**Where it is used**

* **omnicore\_project.omnicore.security.services.SecurityCop** — In `catch()`: `_IP_BAN_TIMEOUT = getattr(dynamic_settings, "SECURITYCOP_IP_BAN_TIMEOUT", 60 * 60 * 6)`; that value is used as the cache TTL when marking the client IP as needing verification (`cache.set(cache_key, True, _IP_BAN_TIMEOUT)`). Used to decide how long the IP remains "suspicious" before the ban expires.

Key: `SECURITYCOP_IP_BAN_TIMEOUT`\
Type: int\
Default: 21600 (6 hours)

**Example**

Use a smaller value (e.g. 3600) for shorter bans, or a larger one for stricter security.

### **59. BasketMaxItemCount**

Maximum total quantity of items allowed in a single basket (sum of all line quantities). When exceeded, the basket condition raises `BasketMaxItemCount` and adding/updating items is blocked.

**Where it is used**

* **omnishop.baskets.conditions.basket\_item\_max\_count** — `basket_max_item_count = dj_dynamic_settings.BASKET_MAX_ITEM_COUNT`; if `basket.get_total_quantity() > basket_max_item_count` then `raise exceptions.BasketMaxItemCount(params=(basket_max_item_count,))`. Used when evaluating basket conditions (e.g. before adding to cart).

Key: `BASKET_MAX_ITEM_COUNT`\
Type: int\
Default: 80

**Example**

Lower the value (e.g. 10) to enforce a stricter cap; raise it for high-quantity B2B baskets.

### **60. GroupedProductPriceSelector**

Dotted path to the callable that selects the displayed price for a grouped product (e.g. min, max, or sum of variant prices).

**Where it is used**

* **omnishop.catalogs.selector.get\_group\_product\_price\_selector** — Returns `import_string(dynamic_settings.GROUPED_PRODUCT_PRICE_SELECTOR)`; that callable is used when resolving the price to show for a grouped product (e.g. in catalog/price logic).

Key: `GROUPED_PRODUCT_PRICE_SELECTOR`\
Type: string (dotted path)\
Default: `omnishop.catalogs.selector.group_product_min_price_selector`

**Example**

* `omnishop.catalogs.selector.group_product_min_price_selector` — show minimum variant price.
* `omnishop.catalogs.selector.group_product_max_price_selector` — show maximum variant price.
* `omnishop.catalogs.selector.group_product_sum_price_selector` — show sum of variant prices.

See [Grouped Products & Combinations](https://docs.akinon.com/pages/BlcCNPtt4ZVLaW9WZATP#id-2.-pricing) for when the price is recalculated and how it differs from the total shown on the combination detail page.

### **61. ListSimpleInsteadOfMeta**

When `true`, a simple (child) product can be chosen as the listable product for a group instead of the meta (parent). When `false`, the listable product is the meta product. Affects which product is used for listing/display and URL generation.

**Where it is used**

* **omnishop.products.service** — In product creation and meta creation: `list_simple = dynamic_settings.LIST_SIMPLE_INSTEAD_OF_META`; when true, listable is resolved from children with `is_listable=True`; when false, `product_listable = parent`. Also in `_create_product_meta`: `is_listable = not is_listable and not list_simple`.

Key: `LIST_SIMPLE_INSTEAD_OF_META`\
Type: boolean\
Default: false

**Example**

Set to `true` when you want the listable product in listing pages to be a specific variant (simple) rather than the group (meta).

### **62. NoReplyEmail**

Sender (From) address used for system emails that should not receive replies (e.g. order confirmations, shipping notifications, verification codes). Validated as a valid email.

**Where it is used**

* **omnishop.users.service** — Verification code email: `from_email = dj_dynamic_settings.NO_REPLY_EMAIL`. Other code paths use `settings.NO_REPLY_EMAIL` or `getattr(settings, 'NO_REPLY_EMAIL', 'noreply@akinon.com')` for order/shipping/contact emails (Django settings; dynamic value can override at runtime if wired).
* **omnishop.orders.service** — Multiple email sends use `from_email=settings.NO_REPLY_EMAIL` for order and shipping emails.

Key: `NO_REPLY_EMAIL`\
Type: string\
Default: <noreply@akinon.com>

**Example**

Set to your no-reply address (e.g. `noreply@yourdomain.com`).

### **63. EmailSmtpConfiguration**

SMTP connection settings for sending email (validated by `EmailSmtpConfigurationSerializer`). Typically includes host, port, username, password, use\_tls, use\_ssl, ssl\_certfile, ssl\_keyfile, timeout. Passed to the Django SMTP backend so sending uses these values instead of or in addition to Django `EMAIL_*` settings.

**Where it is used**

* **omnishop.cms.email.backends.smtp.EmailBackend** — In `__init__`: `conf = dynamic_settings.EMAIL_SMTP_CONFIGURATION` then `conf.update(**kwargs)` and `super().__init__(**conf)`; the backend is thus configured from this setting.

Key: `EMAIL_SMTP_CONFIGURATION`\
Type: object\
Default: derived from Django `EMAIL_HOST`, `EMAIL_PORT`, etc.

**Example**

Override at runtime for different SMTP credentials or TLS/SSL without changing Django settings.

### **64. PushNotificationActive**

When `true`, push notification dispatch is enabled (order created, status changed, basket offer, etc.). When `false`, the notification decorator skips sending.

**Where it is used**

* **omnishop.libs.push\_notification\_gateways.service.NotificationDispatchService** — Methods are decorated with `@notification_activated`; the decorator checks `getattr(dynamic_settings, 'PUSH_NOTIFICATION_ACTIVE', False)` and only runs the method (e.g. `notify_order_created`, `notify_order_status_changed`) when true.

Key: `PUSH_NOTIFICATION_ACTIVE`\
Type: boolean\
Default: false

**Example**

Set to `true` when using a push gateway (EuroMessage, Webinstats, etc.); ensure `PUSH_NOTIFICATION_GATEWAY` and `PUSH_NOTIFICATION_GATEWAYS` are configured.

### **65. PushNotificationGateway**

Name of the active push notification gateway. Must match a key in `PUSH_NOTIFICATION_GATEWAYS`. The gateway is instantiated with that entry's `klass` and `conf`.

**Where it is used**

* **omnishop.users.service.PushNotificationService** — `gateway` property: `gateway_name = dj_dynamic_settings.PUSH_NOTIFICATION_GATEWAY`, `gateway_settings = dj_dynamic_settings.PUSH_NOTIFICATION_GATEWAYS.get(gateway_name)`; then `klass = import_string(gateway_settings['klass'])`, `gateway = klass(**gateway_settings['conf'])`. Used for `notify_order_created`, `notify_order_status_changed`, etc.

Key: `PUSH_NOTIFICATION_GATEWAY`\
Type: string\
Default: null (from Django `PUSH_NOTIFICATION_GATEWAY`)

**Example**

e.g. `"euro_message"` or `"webinstats"`; must exist as a key in `PUSH_NOTIFICATION_GATEWAYS`.

### **66. PushNotificationGateways**

Dictionary mapping push notification gateway names to their configuration (typically `klass` and `conf`). The active gateway is selected by `PUSH_NOTIFICATION_GATEWAY`.

**Where it is used**

* **omnishop.users.service.PushNotificationService** — `gateway` property looks up `dj_dynamic_settings.PUSH_NOTIFICATION_GATEWAYS.get(gateway_name)` and instantiates the backend from `klass` and `conf`.

Key: `PUSH_NOTIFICATION_GATEWAYS`\
Type: object\
Default: `{}` (from Django `PUSH_NOTIFICATION_GATEWAYS`)

**Example**

e.g. `{"euro_message": {"klass": "...", "conf": {...}}, "webinstats": {...}}`.

### **67. IgnoreDeletedItemsSignalConfig**

List of model labels (e.g. `app_label.ModelName`) for which delete signals are ignored. When a model in this list is deleted, a `DeletedItem` record is not created in the datawarehouse (used to avoid syncing certain internal deletions).

**Where it is used**

* **omnishop.datawarehouse.receivers.item\_delete\_receiver** — On delete: `if sender._meta.label not in dynamic_settings.IGNORE_DELETED_ITEMS_SIGNAL` then `DeletedItem.objects.create(...)`; otherwise the deletion is ignored for the datawarehouse.

Key: `IGNORE_DELETED_ITEMS_SIGNAL`\
Type: array (list of model labels)\
Default: from Django `IGNORE_DELETED_ITEMS_SIGNAL` (e.g. includes AuditEvent, Session, DeletedItem)

**Example**

Add model labels (e.g. `"sessions.Session"`) to avoid creating DeletedItem records for those models.

### **68. ShippingProvidersSetting**

Configuration for shipping providers (carriers). Keys are provider identifiers (e.g. carrier enum values); each entry typically has `conf` with provider-specific options (e.g. tracking URL generation). Used when resolving tracking URLs and carrier behaviour.

**Where it is used**

* **omnicore\_project.omnicore.orders.enums** — In `get_tracking_url()`: `provider = settings.SHIPPING_PROVIDERS.get(self.value)`; `conf` is used e.g. for `generate_tracking_url` on the extension provider.
* **omnishop.orders.settings.conf** — Setting defined here; tests and shippings use it for provider config.

Key: `SHIPPING_PROVIDERS`\
Type: object\
Default: `{}` (from Django `SHIPPING_PROVIDERS`)

**Example**

Dict keyed by carrier identifier with `conf` (and optionally other keys) per provider.

### **69. EasyReturnPackageStrategy**

Dotted path to the strategy class that determines easy-return package behaviour (e.g. rule-based vs selection-based). The strategy is used to build easy-return objects for order item cancellation.

**Where it is used**

* **omnishop.orders.strategies.get\_easy\_return\_package\_strategy** — `klass = import_string(dynamic_settings.EASY_RETURN_PACKAGE_STRATEGY)`; returns an instance used for `get_easy_return_object` / `get_easy_return_objects`.
* **omnishop.shippings.resources.views** — Appointment-date view checks `dynamic_settings.EASY_RETURN_PACKAGE_STRATEGY != EasyReturnPackageStrategyType.selection_based_easy_return_package_strategy.value` and returns 400 when the strategy is not selection-based (appointment dates only supported for that strategy).

Key: `EASY_RETURN_PACKAGE_STRATEGY`\
Type: string (dotted path)\
Default: `omnishop.orders.strategies.RuleBasedEasyReturnPackageStrategy`

**Example**

Use `omnishop.orders.strategies.SelectionBasedEasyReturnPackageStrategy` when appointment-date selection is required for easy return.

For how this setting affects carrier selection and easy return code generation, see the [Easy Return](https://docs.akinon.com/technical-guides/commerce/easy-return.md) documentation.

### **70. OrderNumberGeneratorConf**

This configuration customizes the order number format by defining a **pattern** (with optional prefix/postfix) and **numbers\_length**. Only used when the order number generator is set to a function that reads this conf (e.g. `generate_order_number_v2`).

**Where it is used**

* **omnishop.orders.generator.generate\_order\_number\_v2** — `conf = dynamic_settings.ORDER_NUMBER_GENERATOR_CONF`; uses `conf["pattern"]` and `conf["numbers_length"]` to build the order number (time-based + increment + random, formatted by pattern). The Django env var `ORDER_NUMBER_GENERATOR` must point to this (or another) generator for the conf to apply.

Key: `ORDER_NUMBER_GENERATOR_CONF`\
Type: object\
Default: { "pattern": "{numbers}", "numbers\_length": 12 }

**Parameters**

* **pattern**\
  Defines the format of the order number.\
  The `{numbers}` placeholder represents the auto-generated numeric value.\
  Static text can be added before or after this placeholder to define a prefix and/or postfix.
* **numbers\_length**\
  Specifies the length of the numeric value generated for the `{numbers}` placeholder.

**Example 1:**\
{“pattern”: “ON\_{numbers}”, “numbers\_length”: 12}\
Output: “ON\_123456789012”

In this example, the order number starts with the `ON_` prefix followed by a 12-digit numeric value.

**Example 2:**\
{“pattern”: “{numbers}AK”, “numbers\_length”: 5}\
Output: “12345AK”

In this example, the order number starts with a 5-digit numeric value and ends with the `AK` postfix.

### **71. SendShippingNotificationsPartially**

When `true`, shipping notifications (email, SMS, push) can be sent per order item when that item is shipped (partial shipping). When `false`, the full-order shipping notification is used (sent once when the order reaches shipped with a tracking number).

**Where it is used**

* **omnishop.orders.actions** — `send_shipping_notifications` is registered only when `not dynamic_settings.SEND_SHIPPING_NOTIFICATIONS_PARTIALLY` (full-order flow). `send_partial_shipping_notifications` is registered when `dynamic_settings.SEND_SHIPPING_NOTIFICATIONS_PARTIALLY` and runs per order item (shipped + tracking number), calling `OrderShippingNotificationService.send_partial_shipping_mail/sms/notification`.

Key: `SEND_SHIPPING_NOTIFICATIONS_PARTIALLY`\
Type: boolean\
Default: False

**Example**

Set to `true` when you ship items separately and want one notification per shipped item; set to `false` for one notification per order.

### **72. SendShippingDeliveredNotificationsPartially**

When `true`, delivered notifications can be sent per order item when that item is delivered. When `false`, the full-order delivered notification is used (once when the order reaches delivered).

**Where it is used**

* **omnishop.orders.actions** — `send_order_delivery_notifications` runs only when `not dynamic_settings.SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY` (full-order delivered). `send_partial_shipping_delivered_notifications` runs when `dynamic_settings.SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY` and calls `OrderShippingNotificationService.send_partial_shipping_delivered_mail` etc. per item.

Key: `SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY`\
Type: boolean\
Default: False

**Example**

Set to `true` for per-item delivered emails/SMS; set to `false` for one delivered notification per order.

### **73. ExtraCancelRules**

Extra rules for order cancellation. Supports `extra_direct_cancellable_statuses` (list of status codes to add to cancellable), `has_invoice` (block cancel if order has invoice), and `hour_gap` (time window: `is_active`, `time` in minutes) to block cancellation after a delay.

**Where it is used**

* **get\_cancellable\_statuses** — Extends the default cancellable statuses with the status codes listed in `extra_direct_cancellable_statuses`.
* **validate\_order\_cancellation** — Checks `has_invoice` (raises if the order has an invoice number) and `hour_gap` (raises if the cancellation window has expired).

Key: `EXTRA_CANCEL_RULES`\
Type: object\
Default: `{}`

**Order Status Codes**

`extra_direct_cancellable_statuses` accepts **status codes** (not status names) and **extends** the default cancellable statuses — it does not replace them. Statuses marked as default are always cancellable regardless of this setting.

| Status Name              | Code  | Default |
| ------------------------ | ----- | ------- |
| `cancellation_waiting`   | `50`  |         |
| `cancelled`              | `100` |         |
| `waiting`                | `200` |         |
| `payment_waiting`        | `300` | ✓       |
| `confirmation_waiting`   | `350` | ✓       |
| `approved`               | `400` | ✓       |
| `waiting_for_substitute` | `430` |         |
| `preparing`              | `450` |         |
| `shipped`                | `500` |         |
| `shipped_and_informed`   | `510` |         |
| `ready_for_pickup`       | `520` |         |
| `attempted_delivery`     | `540` |         |
| `delivered`              | `550` |         |
| `refunded`               | `600` |         |

**Example**

```json
{
  "extra_direct_cancellable_statuses": ["450"],
  "has_invoice": true,
  "hour_gap": {
    "is_active": true,
    "time": 60
  }
}
```

Extends the default cancellable statuses with `preparing` (`450`), blocks cancellation if the order has an invoice, and blocks cancellation 60 minutes after order creation.

### **74. CheckoutStockAvailableCheck**

When `true`, order creation (checkout) re-checks stock for each basket item and blocks creation if any item is not available to buy (e.g. `is_available_to_buy` fails for the requested quantity). When `false`, stock is not re-validated at checkout.

**Where it is used**

* **omnishop.orders.service.OrderService.create\_order** — `checkout_stock_available_check = getattr(dj_dynamic_settings, 'CHECKOUT_STOCK_AVAILABLE_CHECK', None)`; if true, for each basket item loads product stock and calls `basket_item.is_available_to_buy(basket_item.get_quantity_for_stock())`; if not available, order creation fails.

Key: `CHECKOUT_STOCK_AVAILABLE_CHECK`\
Type: boolean\
Default: false

**Example**

Set to `true` to avoid creating orders for out-of-stock items; set to `false` if stock is enforced elsewhere or not required.

### **75. SendRefundResultNotifications**

When `true`, after an order transitions to refunded the system sends refund result SMS and push notification to the user. When `false`, no refund result notification is sent.

**Where it is used**

* **omnishop.orders.actions** — `send_refund_result_notifications` is registered with condition `getattr(dynamic_settings, "SEND_REFUND_RESULT_NOTIFICATIONS", False)` and when order goes to `refunded`; it calls `OrderTaskService.send_refund_result_sms` and `send_refund_result_notification`.

Key: `SEND_REFUND_RESULT_NOTIFICATIONS`\
Type: boolean\
Default: false

**Example**

Set to `true` to notify users when their refund is processed.

### **76. PickupLocationProviderBaseUrl**

Base URL for the pickup location provider API (e.g. for click-and-collect). **Deprecated:** Prefer using `PICKUP_LOCATION_PROVIDER` (with `klass` and `conf`) instead.

**Where it is used**

* **omnishop.address.pickup\_locations.provider** — In the provider: `base_url = self.base_url or dynamic_settings.PICKUP_LOCATION_PROVIDER_BASE_URL`; used in `get_url()` to build API URLs for pickup locations. Also used when the provider is instantiated with conf that does not override `base_url`.

Key: `PICKUP_LOCATION_PROVIDER_BASE_URL`\
Type: string\
Default: `""`

**Example**

Set to the base URL of your pickup-location API (e.g. `https://api.example.com/pickup`); consider migrating to `PICKUP_LOCATION_PROVIDER`.

### **77. InstallmentFilters**

List of installment filter configs. Each entry has `klass` (dotted path to filter class) and `kwargs` (options). Filters are applied in order to reduce or format installment options at checkout (e.g. by bank, basket amount).

**Where it is used**

* **omnishop.payments.strategies** — In `_filter_installments`: `for installment_filter in dynamic_settings.INSTALLMENT_FILTERS`; each filter is instantiated with `import_string(installment_filter["klass"])(**installment_filter["kwargs"])` and its `filter(basket, installments, **kwargs)` is called to get filtered installments and optional messages.

Key: `INSTALLMENT_FILTERS`\
Type: array\
Default: `()` (from Django `INSTALLMENT_FILTERS`)

**Example**

`[{"klass": "omnishop.payments.filters.SomeFilter", "kwargs": {"min_amount": 100}}]`

### **78. LoyaltyMoneyEnabled**

When `true`, loyalty money (balance from loyalty account) can be used as a payment method; basket exposes `loyalty_amount` and payment strategies may allow paying with loyalty. When `false`, loyalty amount is zero and loyalty payment is disabled.

**Where it is used**

* **omnishop.orders.models.Order** — `loyalty_amount` cached property: `if not dynamic_settings.LOYALTY_MONEY_ENABLED: return 0`; otherwise computes available loyalty balance for the order currency.
* **omnishop.payments.strategies** — `pay_loyalty_money()` returns `False` when `not dynamic_settings.LOYALTY_MONEY_ENABLED`; controls whether loyalty can be applied as payment.

Key: `LOYALTY_MONEY_ENABLED`\
Type: boolean\
Default: false

**Example**

Set to `true` when you offer loyalty points/cash as a payment option at checkout.

### **79. SwapPrettyUrlsForNotListableProducts**

When `true`, pretty URL generation for products uses different logic when the canonical product is not listable: e.g. `incr_new_path` in `ProductUrlGenerator` considers existing URLs with a numeric suffix pattern and can swap to a listable variant. When `false`, the default (super) behaviour is used and non-listable products may not get the same URL handling.

**Where it is used**

* **omnishop.prettyurls.generators.ProductUrlGenerator** — In `incr_new_path`: `if not getattr(dynamic_settings, 'SWAP_PRETTY_URLS_FOR_NOT_LISTABLE_PRODUCTS', False): return super().incr_new_path(...)`; when true, uses custom logic (regex, annotate index, existing\_urls) to handle new paths for non-listable products.

Key: `SWAP_PRETTY_URLS_FOR_NOT_LISTABLE_PRODUCTS`\
Type: boolean\
Default: false

**Example**

Set to `true` when you want pretty URLs to resolve to a listable variant when the primary product is not listable.

### **80. ImageOptimizationLimit**

Quality threshold used when Commerce compresses an image at **upload time**. The uploaded image is re-encoded as JPEG (quality 95) and the compressed version is stored **only if** its file size is below this percentage of the original; otherwise the original is kept. This affects file size and encoding quality only — it does **not** change the image dimensions, and `GIF`/`PNG` files are skipped entirely.

**Where it is used**

* **omnicore\_project.omnicore.products.enums** — When saving an image-type attribute: `quality_limit = get_setting("IMAGE_OPTIMIZATION_LIMIT", default=90)`; value is passed to `adjust_image_quality(..., limit=quality_limit)` before saving to storage.
* **omnicore\_project.omnicore.eav.models** — Same pattern for image attribute handling.

Key: `IMAGE_OPTIMIZATION_LIMIT`\
Type: int\
Default: 90

**Example**

Lower (e.g. 70) for smaller file sizes; higher (e.g. 95) for better quality and larger files.

#### Upload-time optimization vs. CDN serve-time optimization

`IMAGE_OPTIMIZATION_LIMIT` is often confused with a second, unrelated mechanism: the automatic image optimization performed by the CDN when an image is **served**. These are two different layers, and only the first one is a Commerce dynamic setting.

**Upload-time optimization (Commerce).** When an image is uploaded, Commerce may re-compress it once before it is written to storage, as governed by `IMAGE_OPTIMIZATION_LIMIT` (see above). This step changes only the stored file's encoding quality and size. It never resizes the image, and it does not apply to `GIF`/`PNG` files. Note that images uploaded through **Content Management widgets** are not resized or thumbnailed by Commerce at all — `THUMBNAIL_OPTIONS` applies to product images only.

**CDN serve-time optimization (infrastructure).** Independently of anything stored in Commerce, the CDN automatically optimizes images as it delivers them to the browser, so that each visitor receives an efficiently sized and encoded asset. Because of this, the file a client downloads from a CDN URL can differ in **format** (for example, a JPEG may be served as WebP) or in **dimensions** from the file that was uploaded, and the delivered variant can vary depending on the requesting browser or device. This is expected behaviour and is not a defect: an image uploaded at, say, 1920×1080 may legitimately be served at smaller dimensions or in a different format on the storefront.

This serve-time optimization is part of the platform infrastructure. It is **not** controlled by `IMAGE_OPTIMIZATION_LIMIT` or any other Commerce dynamic setting, and it cannot be configured by the partner. Changes to this behaviour can only be made by the Akinon platform/DevOps team.

| Aspect                   | `IMAGE_OPTIMIZATION_LIMIT` (upload-time)     | CDN optimization (serve-time)                     |
| ------------------------ | -------------------------------------------- | ------------------------------------------------- |
| When it runs             | Once, when the image is uploaded to Commerce | Every time an image is requested from the CDN     |
| Layer                    | Commerce application                         | CDN / platform infrastructure                     |
| What it changes          | Encoding quality and stored file size        | Delivered format (e.g. WebP) and/or dimensions    |
| Varies by browser/device | No                                           | Yes — the served variant can depend on the client |
| Changes dimensions       | No                                           | Yes, it can                                       |
| Configurable by          | Merchant/partner, via this dynamic setting   | Akinon platform/DevOps team only                  |
| Related setting          | `IMAGE_OPTIMIZATION_LIMIT`                   | None (no Commerce setting)                        |

If a partner reports that an image is downloaded from a storefront CDN URL in a different size or format than the one they uploaded, this is the CDN serve-time optimization at work and is expected behaviour, not the effect of `IMAGE_OPTIMIZATION_LIMIT`.

### **81. ListableProductRules**

List of dotted paths to rule callables that filter or sort variant products to pick the listable one for a group/meta product. Rules are applied in order (e.g. image\_rule → keep variants with image; is\_listable\_rule → keep listable; min\_price\_rule → sort by price ascending).

**Where it is used**

* **omnishop.products.listable\_rules.get\_listable\_product\_rules** — `rules = dynamic_settings.LISTABLE_PRODUCT_RULES`; returns `[import_string(r) for r in rules]`.
* **omnishop.products.service** — When resolving the listable product: `for rule in get_listable_product_rules(): filtered_variants = rule(filtered_variants)`; the final variant(s) determine the listable product.

Key: `LISTABLE_PRODUCT_RULES`\
Type: list (dotted paths)\
Default: `["omnishop.products.listable_rules.image_rule", "omnishop.products.listable_rules.is_listable_rule"]`

Available rules:

* `omnishop.products.listable_rules.image_rule` — Prefers variants with at least one image.
* `omnishop.products.listable_rules.is_listable_rule` — Prefers the currently listable variant.
* `omnishop.products.listable_rules.stock_rule` — Prefers variants that have stock in any segment.
* `omnishop.products.listable_rules.all_stock_rule` — Prefers variants that have stock across all segments (stock lists). Useful for multi-inventory setups. Falls back to all candidates if no variant qualifies.
* `omnishop.products.listable_rules.all_variants_have_image_rule` — Requires **every** active variant in the group to have an active image. If a single one has none, the whole group is left without a listable product; there is no fallback to the variants that do have an image.
* `omnishop.products.listable_rules.min_price_rule` — Prefers the variant with the lowest price.
* `omnishop.products.listable_rules.max_price_rule` — Prefers the variant with the highest price.

**Important behaviour:**

* The rules only apply to groups whose variants compete for a listable position — that is, when the attribute set defines variant listable attributes and the variant carries a value for at least one of them, or when `LIST_SIMPLE_INSTEAD_OF_META` is enabled. A simple product without a parent is listable purely on whether it has an image. Only **active** variants of the group are considered as candidates.
* The rules are evaluated when a product is updated or deactivated, when a product's first image is created or its last image is deleted, and — while `LIST_SIMPLE_INSTEAD_OF_META` is enabled — when a variant's price or stock changes. Product **creation** does not run the rules: a newly created variant becomes listable simply because its group has no listable product yet.
* The default configuration is permissive: `image_rule` needs only one variant in the group to have an image, so a colour group stays listable through that single variant even when its siblings have none. `all_variants_have_image_rule` is the opt-in strict counterpart — use it when a group must not be listed until every variant (for example every size of the same colour) has its own image.
* Place `all_variants_have_image_rule` **first** in the list. The rules are applied in order to a shrinking candidate list, and the last non-empty result wins: any rule in front of it (`image_rule`, `is_listable_rule`, `stock_rule`, …) has already removed the imageless variants from that list or has already produced a winner, which makes the group-wide check a no-op.
* Unlike `stock_rule` and `all_stock_rule`, `all_variants_have_image_rule` does **not** fall back to the full candidate list. An incomplete group produces no listable product at all, so the group is not listed on the storefront and is not indexed for search until the missing images are added.
* The rule also governs the hand-over that happens when the variant currently holding the listable position becomes inactive and no other variant qualifies. By default the position passes to the first active variant that has an image; when `all_variants_have_image_rule` is configured, the hand-over happens only if every active variant of the group has an image — otherwise the group is left with no listable product. This hand-over check only looks at whether the rule is present in `LISTABLE_PRODUCT_RULES`, so it is strict regardless of the rule's position; the main evaluation described above is the one that depends on the order.
* Because the whole variant family is re-evaluated, image changes flip the group in both directions: deleting the last active image of one variant delists the entire group, and adding that image back makes the group listable again.

**Example**

Require a complete image set before a group can be listed, and keep the cheapest variant as the listable one:

```json
[
  "omnishop.products.listable_rules.all_variants_have_image_rule",
  "omnishop.products.listable_rules.min_price_rule"
]
```

### **82. IsMarketplace**

When `true`, the shop operates as a marketplace (e.g. multiple sellers or data sources). Basket and product logic may enforce data-source or seller checks. When `false`, single-seller behaviour.

**Where it is used**

* **omnishop.baskets.resource.serializers** — In `validate()`: `is_marketplace = dynamic_settings.IS_MARKETPLACE`; when true, `_validate_datasource(attrs)` is called so basket items are validated against allowed data sources.

Key: `IS_MARKETPLACE`\
Type: boolean\
Default: false

**Example**

Set to `true` when you have multiple sellers or data sources and need datasource validation on add-to-basket.

### **83. AttributesOrderReplace**

Map of attribute key → another attribute key. When building product attribute display/order data, if the product has both the source key and the target key, the **order** of the source attribute is taken from the target attribute's order (used to reorder or align attribute display).

**Where it is used**

* **omnishop.products.models** — When building attribute data (e.g. for filters/display): `reorder_attr = getattr(dynamic_settings, 'ATTRIBUTES_ORDER_REPLACE', {})`; if `reorder_attr.get(attribute_key)` exists and that target is in `product.attributes`, the order value from the target attribute is used for the current attribute's order.

Key: `ATTRIBUTES_ORDER_REPLACE`\
Type: object\
Default: `{}`

**Example**

`{"color": "size"}` to use the order of the "size" attribute for the "color" attribute when both exist.

### **84. HideGroupedProductsOnSearch**

When `true`, grouped products are hidden from search by blanking their (and their sub-products') name and search\_text in the search index so they do not match. When `false`, grouped products can appear in search results.

**Where it is used**

* **omnishop.search.indexer** — When indexing a grouped product: `if instance.product_type == ProductTypes.grouped and dynamic_settings.HIDE_GROUPED_PRODUCTS_ON_SEARCH:` then for each sub\_product `sub_product_.name, sub_product_.search_text = '', ''` so they are not findable in search.

Key: `HIDE_GROUPED_PRODUCTS_ON_SEARCH`\
Type: boolean\
Default: false

**Example**

Set to `true` to only show simple/variant products in search and hide group parents.

See [Grouped Products & Combinations](https://docs.akinon.com/pages/BlcCNPtt4ZVLaW9WZATP#id-4.-search-behavior) for how a combination is indexed and why the change is not instant.

### **85. CategoryProductExtractionStrategy**

Determines how products are displayed on category listing pages. Can be configured independently from `SEARCH_PRODUCT_EXTRACTION_STRATEGY`, allowing search and category pages to behave differently.

Key: `CATEGORY_PRODUCT_EXTRACTION_STRATEGY`\
Type: string (choice)\
Validation: Must be one of the valid strategies listed in `SEARCH_PRODUCT_EXTRACTION_STRATEGY`\
Default: `"omnishop.search.strategies.DefaultProductExtractionStrategy"`

**Valid options:** Same as `SEARCH_PRODUCT_EXTRACTION_STRATEGY` (see setting #86 for the full strategies table).

**Important behaviour:**

* When seller filtering is active (`seller_ids` parameter is present), `OfferProductExtractionStrategy` is automatically applied regardless of this setting.

> **Note:** For Seller Center projects, `OfferProductExtractionStrategy` is recommended for category listings.

**Example:**

```json
"omnishop.search.strategies.OfferProductExtractionStrategy"
```

### **85.1. Category Pre Filter**

Applies a general pre-filter to product queries on category pages. All queries from search, navigation menus, and category listings pass through this filter before executing. When left empty, no pre-filtering is applied and all categories are visible.

Key: `CATEGORY_PRE_FILTER`\
Type: dict\
Validation: Must be a dictionary\
Default: `{}` (no filtering applied)

**Use cases:**

* Presenting different category hierarchies to specific customer segments
* Hiding certain categories by default in multi-marketplace scenarios

**Important behaviour:**

* Misconfiguration (e.g. filtering by a non-existent field) will cause customers to see an empty or broken category tree
* Expects a dict in Django ORM queryset filter syntax

**Example:**

```json
{
  "is_active": true
}
```

### **85.2. Search Pre Filter Kwargs**

Applies a static Elasticsearch pre-filter to all search, category and autocomplete product queries before user filters are applied. Restricts the base product pool at query time, independent of the request or user context. When left empty, no pre-filtering is applied.

Key: `SEARCH_PRE_FILTER_KWARGS`\
Type: dict\
Validation: Must be a dictionary\
Default: `{}` (no filtering applied)

**Use cases:**

* Restricting a channel to show only products belonging to specific categories
* Excluding certain product groups globally across all search and listing pages

**Important behaviour:**

* Unlike `CATEGORY_PRE_FILTER` (which filters the category tree via Django ORM), this filter operates at the Elasticsearch query level and affects product results
* Misconfiguration (e.g. using a non-existent ES field) will cause empty search and category results
* Expects a dict in Elasticsearch field path → value(s) syntax

**Examples:**

Filter by a specific category:

```json
{
  "products.category_ids": ["18068"]
}
```

Filter by specific base codes:

```json
{
  "products.base_code.raw": ["ABC123", "XYZ456"]
}
```

### **86. SearchProductExtractionStrategy**

Determines which variant/sub-product is displayed from a parent product in search results.

Key: `SEARCH_PRODUCT_EXTRACTION_STRATEGY`\
Type: string (choice)\
Validation: Must be one of the valid values below\
Default: `"omnishop.search.strategies.DefaultProductExtractionStrategy"`

**Valid options and their behaviour:**

| Value                                                               | Behaviour                                                                                                                        |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `omnishop.search.strategies.DefaultProductExtractionStrategy`       | Returns the parent product                                                                                                       |
| `omnishop.search.strategies.FirstItemSearchExtractionStrategy`      | Returns the first (cheapest) sub-product                                                                                         |
| `omnishop.search.strategies.ListableFirstProductExtractionStrategy` | Returns the first listable product that has an image                                                                             |
| `omnishop.search.strategies.MinPriceFirstProductExtractionStrategy` | Returns the lowest-priced variant                                                                                                |
| `omnishop.search.strategies.MaxPriceFirstProductExtractionStrategy` | Returns the highest-priced variant                                                                                               |
| `omnishop.search.strategies.AllSubProductsExtractionStrategy`       | Returns all sub-products (max 20)                                                                                                |
| `omnishop.search.strategies.OfferProductExtractionStrategy`         | Returns marketplace seller offers by minimum price; automatically falls back to the cheapest standard product if no offers exist |
| `omnishop.search.strategies.ProductSortingItemExtractionStrategy`   | Returns products based on sorting criteria                                                                                       |

**Important behaviour:**

* `OfferProductExtractionStrategy` is the only strategy that automatically falls back to a standard product when no offers are found
* `OfferProductExtractionStrategy` is designed for Seller Center projects
* **When seller filtering is active, this setting is ignored:** When a search is made with the `seller_ids` parameter, `OfferProductExtractionStrategy` is automatically applied regardless of this setting. This setting only takes effect for searches made without a seller filter.

> **Note:** `CATEGORY_PRODUCT_EXTRACTION_STRATEGY` and `SPECIAL_PAGE_EXTRACTION_STRATEGY` share the same set of valid options.

**Example:**

```json
"omnishop.search.strategies.MinPriceFirstProductExtractionStrategy"
```

### **87. EnableExternalCostCalculator**

When `true`, shipping cost is calculated via the external cost calculator API (`EXTERNAL_COST_CALCULATOR`). When `false`, the Omnitron API client is used for shipping cost.

**Where it is used**

* **omnishop.shippings.calculators** — The calculator's `client` classproperty: `is_calculator_external = getattr(dynamic_settings, 'USE_EXTERNAL_COST_CALCULATOR', False)`; when true, `cls._client = ExternalCostCalculatorApiClient()`; otherwise `OmnitronApiClient()`. That client is used for `calculate_shipping_cost`.

Key: `USE_EXTERNAL_COST_CALCULATOR`\
Type: boolean\
Default: false

**Example**

Set to `true` and configure `EXTERNAL_COST_CALCULATOR` when you use an external shipping cost API instead of Omnitron.

### **88. ExternalCostCalculatorAPI**

Configuration for the external cost calculator API (validated by `ExternalCostCalculatorAPISerializer`). Typically includes `host` (URL) and `token` (auth). Used when `USE_EXTERNAL_COST_CALCULATOR` is true.

**Where it is used**

* **omnishop.shippings.client.ExternalCostCalculatorApiClient** — In `calculate_shipping_cost`: `external_cost_calculator_url = getattr(dynamic_settings, 'EXTERNAL_COST_CALCULATOR', {}).get("host")`, `self.access_token = ...get("token")`; the client POSTs to that URL with the token to get shipping cost.

Key: `EXTERNAL_COST_CALCULATOR`\
Type: object\
Default: `{}`

**Example**

`{"host": "https://api.example.com/calculate-shipping/", "token": "..."}`

### **89. ProductAlertQuantity**

Minimum stock quantity for a product to be considered "in stock" for product alerts. When stock is >= this value, "back in stock" notifications can be sent to users who signed up for alerts.

**Where it is used**

* **omnishop.wishlists.tasks** — In the product alerts task: `product__productstock__stock__gte=dynamic_settings.PRODUCT_ALERT_QUANTITY` filters product alerts so only products with stock at or above this threshold are processed for sending alert emails.

Key: `PRODUCT_ALERT_QUANTITY`\
Type: int\
Default: 1

**Example**

Set to a higher value (e.g. 5) if you only want to notify when there is meaningful stock; keep at 1 for "any stock" alerts.

### **90. ApplePayDomainAssociation**

Content of the Apple Pay domain verification file (merchant domain association). Served at the well-known URL so Apple can verify the domain for Apple Pay.

**Where it is used**

* **omnishop.payments.views.WellKnowView** — For slug `apple-developer-merchantid-domain-association.txt` or `apple-developer-merchantid-domain-association`: `content = getattr(dj_dynamic_settings, 'APPLE_PAY_DOMAIN_ASSOCIATION', '')`; returned as HttpResponse with `text/plain`. Used for Apple Pay domain verification.

Key: `APPLE_PAY_DOMAIN_ASSOCIATION`\
Type: string\
Default: ““

### **91. OfferMiscellaneousAttributeKey**

Product attribute key (e.g. `cannot_be_sold_alone`) that indicates whether an offer product can be sold alone. When this attribute is true on an offer, the product must be bought with another product (e.g. sub\_items or main product); basket and order logic enforce this.

**Where it is used**

* **omnishop.baskets.resource.serializers** — In add/set basket item validation: `offer_miscellaneous_key = dynamic_settings.OFFER_MISCELLANEOUS_ATTRIBUTE_KEY`; used to check `sub_item['product'].attributes.get(offer_miscellaneous_key, False)` and reject unexpected sub items when the offer cannot be sold alone.
* **omnishop.baskets.service** — `offer_miscellaneous_attr_key = dynamic_settings.OFFER_MISCELLANEOUS_ATTRIBUTE_KEY`; used when adding to basket to limit quantity or enforce form/extra product rules for offer/miscellaneous products.
* **omnishop.orders.service** — Same key used for order-level offer/miscellaneous checks.

Key: `OFFER_MISCELLANEOUS_ATTRIBUTE_KEY`\
Type: string\
Default: `cannot_be_sold_alone`

**Example**

Use the attribute key that your product data uses to mark "cannot be sold alone" offers; default is `cannot_be_sold_alone`.

### **92. BasketNamespaceValidator**

This configuration allows you to manage the validations applied within the multi-basket feature.

Key: `BASKET_NAMESPACE_VALIDATORS`\
Type: list\
Default:

```
[ 
   {
       "validator_klass":    "omnishop.baskets.validator.NullNamespaceValidator",
       "kwargs": {}
   },
   {
       "validator_klass": "omnishop.baskets.validator.ActiveBasketCountValidator",
       "kwargs": {
           "limit": 5
       }
   }
]
```

#### **Possible Values**

**NullNamespaceValidator**

Regardless of whether the multibasket feature is used or not, the namespace field cannot be null when adding products to the basket. The field should either be left out entirely or filled with a valid value.

* **For brands that do not want to use the multibasket feature,** the `NullNamespaceValidator` (which is set as the default) should be used. This validator prevents any information from being sent in the namespace field.
* **For brands that want to use the multibasket feature,** the `NullNamespaceValidator` should not be used.

**Key:**

```
{
    "validator_klass": "omnishop.baskets.validator.NullNamespaceValidator",
    "kwargs": {}
}
```

**NamespaceDataSourceValidator**

Restricts the namespaces a user can enter to the slugs associated with the data source. Any additional namespaces that should be permitted can be added through `allowed_custom_namespaces`.\
**Key:**

```
{
    "validator_klass": "omnishop.baskets.validator.NamespaceDataSourceValidator",
    "kwargs": {
        "allowed_custom_namespaces": ["custom-namespace"]
    }
}
```

**ActiveBasketCountValidator**\
This feature limits the number of baskets a user can create. By default, the limit is set to 5, but it can be adjusted by adding a validator, as shown below.\
**Key:**

```
{
    "validator_klass": "omnishop.baskets.validator.ActiveBasketCountValidator",
    "kwargs": {
        "limit": 2
    }
}
```

### **93. CheckoutShippingOptionSelectionPage**

This configuration determines which page will be used for displaying shipping options.

Key: `CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE`\
Type: string\
Default: ShippingOptionSelectionPage

#### **Possible Values**

**ShippingOptionSelectionPage**

* The standard shipping option page.

**DataSourceShippingOptionSelectionPage**

* This page is selected to list shipping options specific to the seller.

**AttributeBasedShippingOptionSelectionPage**

* This page is selected to group shipping options based on the attributes specified in the product.

**RemoteAttributeBasedShippingOptionSelectionPage**

* This page groups shipping options by delivery groups decided by a remote service, which can also split the quantity of a basket line across groups. Requires `REMOTE_ATTRIBUTE_BASED_SHIPPING_OPTION_PROVIDER`. See [Attribute Based Shipping Options](https://docs.akinon.com/technical-guides/commerce/attribute-based-shipping-options.md#remote-attribute-based-shipping-options).

**RemoteShippingOptionSelectionPage**

* This page lists shipping options fetched from a remote service. Requires `REMOTE_SHIPPING_OPTION_PROVIDER`.

### **94. AttributeKeyForAttributeBasedShippingOption**

This configuration is required to group shipping options specific to a product. The shipping option details are stored in the product attributes, and this setting defines the key where that information is kept.

**Note**: The `CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE` configuration must be set to `AttributeBasedShippingOptionSelectionPage`.

Key: `ATTRIBUTE_KEY_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION`\
Type: string\
Default: null

### **94.1. RemoteShippingOptionProvider**

Configuration for the remote shipping option provider used to fetch available shipping options from an external service (e.g. extension). The provider is instantiated with `klass` and `conf`; it must implement `get_shipping_option_slugs(pre_order)` and return a list of shipping option slugs. When using this provider, set `CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE` to `REMOTE_SHIPPING_OPTION_SELECTION_PAGE` so checkout uses the remote flow. See [Extension Shipping Option Flows](https://github.com/akinon/docs/tree/main/apireference/flows/extension-shipping-option-flows.md) for the request and response contract.

**Where it is used**

* **omnishop.shippings.service.RemoteShippingOptionService** — In `__init__`: `remote_shipping_option_provider = dynamic_settings.REMOTE_SHIPPING_OPTION_PROVIDER`; `klass = import_string(remote_shipping_option_provider["klass"])`, `self.provider = klass(**conf)`. In `get_remote_shipping_options(pre_order)`: calls `self.provider.get_shipping_option_slugs(pre_order)` then resolves `ShippingOption` objects by slug and applies rules/calculators. Exceptions from the remote provider (timeout, provider error, validation) use `omnishop.shippings.remote_shipping_options.exceptions` (e.g. `RemoteShippingOptionTimeoutException`, `RemoteShippingOptionProviderException`).

Key: `REMOTE_SHIPPING_OPTION_PROVIDER`\
Type: object (`klass` + `conf`)\
Default: `{"klass": "omnishop.shippings.remote_shipping_options.providers.ExtensionShippingOptionProvider", "conf": {"base_url": "", "username": "", "password": ""}}`

**Example**

```json
{
    "klass": "omnishop.shippings.remote_shipping_options.providers.ExtensionShippingOptionProvider",
    "conf": {
        "base_url": "https://extension.example.com",
        "username": "api_user",
        "password": "api_pass"
    }
}
```

Set `CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE` to `REMOTE_SHIPPING_OPTION_SELECTION_PAGE` when using this provider.

### **94.2. RemoteAttributeBasedShippingOptionProvider**

Configuration for the remote provider used by the remote attribute based shipping flow. The provider is instantiated with `klass` and `conf`. It sends the basket and shipping address to an external service (e.g. extension), which returns how the quantity of each basket line is allocated across delivery groups (e.g. `express`, `standart`). The basket itself is not changed. See [Remote Attribute Based Shipping Flows](https://github.com/akinon/docs/tree/main/apireference/flows/remote-attribute-based-shipping-flows.md) for the request and response contract and [Attribute Based Shipping Options](https://docs.akinon.com/technical-guides/commerce/attribute-based-shipping-options.md#remote-attribute-based-shipping-options) for the setup.

**Note**: The `CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE` configuration must be set to `RemoteAttributeBasedShippingOptionSelectionPage`.

Key: `REMOTE_ATTRIBUTE_BASED_SHIPPING_OPTION_PROVIDER`\
Type: object (`klass` + `conf`)\
Default: `{"klass": "omnishop.shippings.remote_attribute_based_shipping_options.providers.ExtensionAttributeBasedShippingOptionProvider", "conf": {"base_url": "", "username": "", "password": ""}}`

| Field           | Type     | Description                                                                                                                                                           |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `klass`         | `string` | The provider class. The only supported value is `omnishop.shippings.remote_attribute_based_shipping_options.providers.ExtensionAttributeBasedShippingOptionProvider`. |
| `conf.base_url` | `string` | Base URL of the remote service. Requests are sent to `{base_url}/attribute-based-shipping-groups`.                                                                    |
| `conf.username` | `string` | Username for HTTP basic authentication.                                                                                                                               |
| `conf.password` | `string` | Password for HTTP basic authentication.                                                                                                                               |

**Example**

```json
{
    "klass": "omnishop.shippings.remote_attribute_based_shipping_options.providers.ExtensionAttributeBasedShippingOptionProvider",
    "conf": {
        "base_url": "https://extension.example.com",
        "username": "api_user",
        "password": "api_pass"
    }
}
```

### **95. BasketValidators**

Basket validators are used to validate basket items before allowing them to proceed to checkout.

Key: `BASKET_VALIDATORS`\
Type: list\
Default: \[]

#### **Possible Values**

**BasketItemQuantityValidator**

* Validates the quantity limits for products that match the specified `attribute_name` and `attribute_value` pairs.

```
[
    {
        "condition_klass": "omnishop.baskets.validator.BasketItemQuantityValidator",
        "kwargs": {
            "attribute_name": "limited_product",
            "attribute_value": true,
            "upper_limit": 5,
            "lower_limit": 1
        },
        "message": {
            "tr-tr": "{lower_limit} ile {upper_limit} arasinda olmalidir"
        }
    }
]
```

**BasketItemBaseCodeQuantityValidator**

* Similar to `BasketItemQuantityValidator` but groups products by base code for quantity control.

```
[
    {
        "condition_klass": "omnishop.baskets.validator.BasketItemBaseCodeQuantityValidator",
        "kwargs": {
            "attribute_name": "limited_product",
            "attribute_value": true,
            "upper_limit": 5,
            "lower_limit": 1
        },
        "message": {
            "tr-tr": "Base code {} quantitiy exceeded"
        }
    }
]
```

**BasketItemSteppedQuantityValidator**

* Ensures that the quantity of a specific product added to the basket is in multiples of the step value specified in its attributes.

```
[
    {
        "condition_klass": "omnishop.baskets.validator.BasketItemSteppedQuantityValidator",
        "kwargs": {
            "attribute_name": "integration_urun_artis_miktar",
            "upper_limit_attribute_name": "integration_max_quantity",
            "lower_limit_attribute_name": "integration_min_quantity",
        },
        "message": {
            "tr-tr": "{step}'nin katlari ve {lower_limit} ile {upper_limit} arasinda olmalidir",
        }
    }
]
```

**AttributeValidator**

* Validates whether products that match specified `attribute_name` and `expected_value` pairs can be added to the basket. If the `attribute_name` is absent in the product's attributes, validation is bypassed.

```
[
    {
        "condition_klass": "omnishop.baskets.validator.AttributeValidator",
        "kwargs": {
            "attribute_name": "cannot_be_sold_alone",
            "expected_value": false,
            "disabled_on_sub_basket_items": false
        },
        "message": {}
    }
]
```

**SingleDataSourceValidator**

* Validates that only one seller's products are present in the basket.

```
[
    {
        "condition_klass": "omnishop.baskets.validator.SingleDataSourceValidator",
        "kwargs": {},
        "message": {}
    }
]
```

### **96. BasketServiceConditions**

A list of conditions that are checked when an item is added to the basket.

Key: `BASKET_SERVICE_CONDITIONS`\
Type: list\
Default: \[]

#### **Possible Values**

**omnishop.baskets.conditions.basket\_tradable\_item\_is\_single**

* Verifies that only items that can be added alongside a tradable product are allowed in the basket.

**omnishop.baskets.conditions.basket\_user\_max\_quantity**

* Enforces the maximum quantity of a product that a user can purchase. This should be used with the `BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE` setting. It counts the user's orders within the time window (in hours) defined by `BASKET_PRODUCT_USER_MAX_QUANTITY_GAP_HOUR` (default: 24 hours).

**omnishop.baskets.conditions.basket\_item\_max\_count**

* Limits the maximum number of products in the basket. This should be used with the `BASKET_MAX_ITEM_COUNT` setting.

**omnishop.baskets.conditions.bundle\_type\_compatibility\_condition**

* ​​Ensures that certain products, which are not allowed to be in the same basket, are checked for compatibility. This condition should be used in conjunction with the `BUNDLE_TYPE_CONFIGURATION` setting.

**omnishop.baskets.conditions.extra\_product\_quantity\_condition**

* Prevents extra products from being added to the basket as parent items.

### **97. AttributeKeyForMergeableOrderItem**

Defines the attribute that stores information about whether a product is mergeable.

Key: `ATTRIBUTE_KEY_FOR_MERGEABLE_ORDER_ITEM`\
Type: string\
Default: allow\_mergeable\_order\_item

### **98. SendTradeinMailCase**

Controls whether an email is sent regarding the status of trade-in orders.

Key: `SEND_TRADEIN_MAIL_CASE`\
Type: boolean\
Default: false

### **99. AllowTradeinWithOtherProducts**

Determines whether other products can be added to the basket alongside trade-in products.

Key: `ALLOW_TRADEIN_WITH_OTHER_PRODUCTS`\
Type: boolean\
Default: false

### **100. UseOneTimeToken**

Allows the user to log in again using a one-time token. The `OneTimeTokenMiddleware` middleware must also be included.

Key: `USE_ONE_TIME_TOKEN`\
Type: boolean\
Default: true

### **101. BasketProductUserMaxQuantityAttribute**

Defines the attribute that stores information about the maximum quantity of a product that a user can purchase. This should be used in conjunction with the `basket_user_max_quantity` condition.

Key: `BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE`\
Type: string\
Default: `""`

**Example**

Set to the exact content of the file Apple provides for your domain (or leave empty if not using Apple Pay).

### **101.1. BasketProductUserMaxQuantityGapHour**

Defines the time window (in hours) used when enforcing the per-user maximum quantity for a product. Works together with `BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE`.

**Business rule:** "A user cannot purchase more than Y units of this product within the last X hours." — X is this setting's value, Y is the limit defined in the product's attribute.

Key: `BASKET_PRODUCT_USER_MAX_QUANTITY_GAP_HOUR`\
Type: number (int, in hours)\
Validation: Must be an integer\
Default: `24`

**Usage examples:**

* `24` → Orders within the last 24 hours are counted (default)
* `72` → Orders within the last 3 days are counted
* `0` → Falsy; falls back to the default 24-hour window

**Important behaviour:**

* Only non-cancelled and non-refunded orders are counted
* If the relevant attribute is not defined on the product, the limit check is skipped
* Used to prevent stock scalping during flash sales and discounted product events

**Example:**

```json
48
```

### **102. BasketProductMaxQuantityAttribute**

Defines the attribute that stores information about the maximum quantity of a product that can be added to the basket.

Key: `BASKET_PRODUCT_MAX_QUANTITY_ATTRIBUTE`\
Type: string\
Default: “”

### **103. TradeinConf**

Stores the trade-in configurations, including `tradein_product_sku_attribute`, `tradein_product_identifier_field`, and `client` configurations.

Key: `TRADEIN_CONF`\
Type: object\
Default: {}

### **104. CancellationRequestAddressRequired**

Makes address information mandatory when creating a cancellation request for a refund.

Key: `CANCELLATION_REQUEST_ADDRESS_REQUIRED`\
Type: boolean\
Default: false

### **105. IsSubBasketItemQuantitySameAsParent**

Ensures that the quantity of the child item matches the quantity of the parent item when added to the basket.

Key: `IS_SUB_BASKET_ITEM_QUANTITY_SAME_AS_PARENT`\
Type: boolean\
Default: false

### **106. GuestUserRegistrationRequiresEmailVerification**

Requires guest users to verify their email in order to log in after placing an order.

See [Guest User Lifecycle](https://docs.akinon.com/technical-guides/commerce/guest-user-lifecycle.md) for how this setting fits into the guest checkout flow.

Key: `GUEST_USER_REGISTRATION_REQUIRES_EMAIL_VERIFICATION`\
Type: boolean\
Default: false

### **107. BukalemunConfig**

Stores the application credentials required to connect to the Bukalemun application.

Key: `BUKALEMUN_CONFIG`\
Type: object\
Default: {}

### **108. PickupLocationProvider**

Stores the credentials of the relevant application for pickup locations.

Key: `PICKUP_LOCATION_PROVIDER`\
Type: object\
Default:

```
{
    "klass": "omnishop.address.pickup_locations.provider.PickupLocationProvider",
    "conf": {
        "base_url": "",
        "username": "",
        "password": ""
    }
}
```

### **109. RemotePriceAttributeKey**

Defines the attribute that, if present in a product's attributes, allows the product to be re-priced during the checkout step via the client.

Key: `REMOTE_PRICE_ATTRIBUTE_KEY`\
Type: string\
Default: has\_remote\_price

### **110. BasketItemRemotePriceClientConf**

Stores the client credentials used to retrieve the final prices of items in the basket during the checkout step.

Key: `BASKET_ITEM_REMOTE_PRICE_CLIENT_CONF`\
Type: object\
Default:

```
{
    "headers": {
        "Authorization": "Bearer test_token"
    },
    "url": "http://localhost:8000/"
}
```

### **111. ResetBasketOnSegmentChange**

Controls the reset behavior of the basket when the segment changes. If enabled, the basket will reset whenever a new segment is selected.

Key: `RESET_BASKET_ON_SEGMENT_CHANGE`\
Type: boolean\
Default: true

### **112. AkifastUsePhone**

Determines whether the Akifast phone number will be used when creating a user upon logging in with Akifast.

Key: `AKIFAST_USE_PHONE`\
Type: boolean\
Default: true

### **113. ShowProductPriceExtraField**

Controls whether additional information related to the product price will be displayed.

Key: `SHOW_PRODUCT_PRICE_EXTRA_FIELD`\
Type: boolean\
Default: false

### **114. XForwardedForRules**

Defines the rules for handling the 'X-Forwarded-For' header IP addresses.

For example, `{1:2, 2:3}` means the first IP address will be replaced with the second, and the second with the third.

These rules help the server accurately determine the actual client IP address.

Set `CLIENT_IP_RESOLVER_FUNCTION` to `omnicore.utils.get_secure_client_ip` for correct client IP resolution.

Key: `X_FORWARDED_FOR_RULES`\
Type: object\
Default: {}

### **115. DeliveryBagsConf**

Set users manually add bag products to their basket, with full control over the quantity. For example, after adding 5 kg of tomatoes and 3 kg of potatoes to the basket, users can manually include a bag product and adjust its quantity.

Bag products cannot be purchased independently and must be added alongside other products.

Key: `DELIVERY_BAGS_CONF`

* **Sku:** Must contain the SKU information of the Miscellaneous-type delivery bags product where is\_active=True.
* **Is\_active:** Reflects whether the Delivery Bags feature is active or not.
* **Per\_amount:** Defines how many basket amounts the delivery bag can accommodate.
* **Auto\_run:** Specifies whether automatic delivery bags will be used from the Slot page.
* **Min\_quantity:** Indicates the minimum quantity value for the delivery bag. The default value is set to 0.
* **Is\_quantity\_changeable:** Determines if the quantity can be updated by the user on the Delivery Bags page. Accepts a True/False value, with the default set to False.
* **Exclude\_bag\_attribute\_name:** Ensures that products with this tag are excluded from the basket amount calculation. The default value is 'exclude\_bag\_attribute\_name'.

!\[]\[image3]

### **116. Attribute Keys For Attribute Based Shipping Option**

This dynamic setting allows you to specify the rule for attribute keys that will be used for grouping shipping options.

For detailed information about this dynamic setting, please refer to the [Attribute Based Shipping Options](https://developers.akinon.com/docs/guide/commerce/attribute-based-shipping-options/#key-dynamic-settings) document.

Key: `ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION`\
Type: Object\
Default: \[ ]

### **117. Auto Use Coupons**

If a coupon applicable to the user's basket exists, the system automatically applies it. The default value is set to `True`.

**Effect:**

* **True:** Coupons are automatically applied.
* **False:** Users must manually select coupons.

Key: `AUTO_USE_COUPONS`\
Type: Boolean\
Default: True

### **118. Basket Item Attributes Max Length KB**

Limits the total size of the attributes field on basket items in kilobytes (KB). The default value is `0`.

**Effect:**

* If a value is specified, the total size of attributes on basket items cannot exceed the specified KB limit.
* A value of `0` allows unlimited size.

Key: `BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB`\
Type: Integer\
Default: 0

### **119. Can Guest Purchase**

Determines whether guest users (users who have not created an account) can make purchases. The default value is set to `True`.

**Effect:**

* **True:** Guests can purchase without creating an account.
* **False:** Users must log in or create an account to make a purchase.

This setting is enabled by default to allow guest users to shop quickly and efficiently. If additional security or user information verification is required, you can set this option to `False`.

See [Guest User Lifecycle](https://docs.akinon.com/technical-guides/commerce/guest-user-lifecycle.md) for how this setting fits into the guest checkout flow.

Key: `CAN_GUEST_PURCHASE`\
Type: Boolean\
Default: True

### **120. Cancellation Request Max Image Count Per Order Item**

Specifies the maximum number of images that can be uploaded per order item during a cancellation request. The default value is `3`.

**Effect:**

* Allows up to the specified number of images.
* A value of `0` disallows image uploads.

This setting can be used to enable users to provide more detailed information with images in their cancellation requests while managing the storage load on the system.

Key: `CANCELLATION_REQUEST_MAX_IMAGE_COUNT_PER_ORDER_ITEM`\
Type: Integer\
Default: 3

### **121. CRM Gateway**

Contains the configuration required for CRM (Customer Relationship Management) integration. Defaults to an empty object `{}`.

**Format:**

This setting is an object format consisting of `{klass, block_guest_for_receiver, conf}`.

| Key                        | Type    | Description                                                                                                                                                                        |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `klass`                    | String  | Specifies the class performing CRM operations.                                                                                                                                     |
| `conf`                     | Obje    | Contains the configuration details for the CRM class.                                                                                                                              |
| `block_guest_for_receiver` | Boolean | Determines if guest users are included in CRM synchronization. If set to `False`, the `CRM_SYNCHRONIZATION_ACTIVE` setting must be set to `True` for synchronization with the CRM. |

Key: `CRM_GATEWAY`\
Type: Object\
Default: { }

### **122. CRM Synchronization Active**

Defines whether CRM synchronization is active during user creation or update operations. This setting controls whether user data is synchronized with the CRM system. By default, it is set to `False`.

**Effect:**

* **True:** CRM synchronization is enabled, and user creation or update operations are synchronized with the CRM system.
* **False:** CRM synchronization is disabled, and user data is not synchronized with the CRM system.

**Note:**

* If this setting is enabled (`True`), CRM synchronization becomes active, and additional processing occurs during every user creation or update operation. This may introduce a performance load on the system, potentially causing delays in database access during periods of high traffic.
* When `CRM_SYNCHRONIZATION_ACTIVE` is set to `True`, the `block_guest_for_receiver` property in the `CRM_GATEWAY` becomes effective.
  * If the user is a guest and `block_guest_for_receiver` is active, synchronization for guest users will be blocked.
  * If `block_guest_for_receiver` is inactive, guest users can be synchronized.

Key: `CRM_SYNCHRONIZATION_ACTIVE`\
Type: Boolean\
Default: False

### **123. DB Templates Prefixes**

Defines the list of valid prefixes for database templates. This setting is used to specify which templates can be stored in the database. The default value is set to `["emails", "sms"]`.

This setting ensures that templates are stored in the correct categories and remain organized. If additional types of templates are required in the system, the relevant prefixes can be added to this list.

**Note:**

* Removing the prefixes `"emails"` and `"sms"` may cause existing templates to malfunction. Therefore, it is recommended to avoid removing these prefixes.

Key: `DB_TEMPLATES_PREFIXES`\
Type: List\[string]\
Default: \["emails", "sms"]

### **124. Deferred Slot Ignored Days**

Specifies which days should be excluded when calculating deferred slot days for appointment-based orders. This configuration allows certain days to be omitted from the calculations. By default, this setting is an empty list.

**Valid Values:**

`[0, 1, 2, 3, 4, 5, 6]`

* `0`: Monday
* `1`: Tuesday
* `2`: Wednesday
* `3`: Thursday
* `4`: Friday
* `5`: Saturday
* `6`: Sunday

**Effect:**

* To exclude a specific day from the calculation of the slot start date, add its numeric value to the list.
* For example, if weekends should be excluded, set `DEFERRED_SLOT_IGNORED_DAYS = [5, 6]`. In this case, Saturday and Sunday will not be considered in the calculations.

Key: `DEFERRED_SLOT_IGNORED_DAYS`\
Type: List\[choices=(0, 1, 2, 3, 4, 5, 6)]\
Default: \[ ]

### **125. Ignore Accept Language Header**

Determines whether the `Accept-Language` header in requests should be ignored. This setting controls whether language preferences are configured based on the header information. By default, it is set to `True`.

**Impact:**

* **True:** `Accept-Language` header is ignored. Language is set via `/i18n/setlang/`.
* **False:** `Accept-Language` header is used. Client language is determined from the header.

**Notes:**

* **Next.js projects:** Must be set to **False**. Otherwise, language switching issues may occur.
* **Django projects:** Should be set to **True**.
* If True → `/i18n/setlang/` endpoint is used.
* If False → `/i18n/setlang/` is disabled, language must be set via `Accept-Language` header.

Key: `IGNORE_ACCEPT_LANGUAGE_HEADER`\
Type: Boolean\
Default: True

### **126. Max Image Dimensions**

This setting is applicable only for cancellation request operations, and it defines the maximum width and height (in pixels) for images. It ensures that the specified dimensions are not exceeded.

**Format:**\
This setting is an object format consisting of a `{width, height}` pair.

* `width`: Maximum width (in pixels).
* `height`: Maximum height (in pixels).

**Note:**

* By controlling image dimensions, you can prevent the system from being overloaded with excessively large images. This setting requires integration with Omnitron, and it is essential for compatibility across both systems.

Key: `MAX_IMAGE_DIMENSIONS`\
Type: Object {“width”, “height”}\
Default:

```py
{
    "width": 2000,
    "height": 2000,
}
```

### **127. Menu Renderer Config**

The `MENU_RENDERER_CONFIG` is a configuration object used to define the structure and behavior of menu rendering in OmniShop. This configuration is represented as an object containing the `generators` and `modifiers` pairs.

**Generator**: Responsible for creating the initial set of menu items. Below is the available generator:

* omnishop.menus.generators.MenuItemModelGenerator

**Modifiers**: Adjust and refine the menu structure and attributes. Below are the available modifiers and their descriptions:

| Path                                             | Description                                                                                                                                                       |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| omnishop.menus.modifiers.SortByLevelMenuModifier | Sorts menu items based on their hierarchy level and predefined sorting order. Ensures the items are displayed in the correct hierarchical sequence.               |
| omnishop.menus.modifiers.SetParentMenuModifier   | Assigns the `parent` property to each menu item. This is achieved by using the `parent_pk` attribute to locate and set the appropriate parent item from the list. |
| omnishop.menus.modifiers.SortingMenuModifier     | Ensures each item is positioned correctly based on its `level` and `sort_order`.                                                                                  |
| omnishop.menus.modifiers.SetSelectedMenuModifier | Identifies and marks the currently selected menu item within the menu tree.                                                                                       |

Key: `MENU_RENDERER_CONFIG`\
Type: Object\
Default: It is recommended to use default configuration for optimal results.

```py
{
    'generators': (
        'omnishop.menus.generators.MenuItemModelGenerator',
    ),
    'modifiers': (
        'omnishop.menus.modifiers.SortByLevelMenuModifier',
        'omnishop.menus.modifiers.SetParentMenuModifier',
        'omnishop.menus.modifiers.SortingMenuModifier',
        'omnishop.menus.modifiers.SetSelectedMenuModifier',
    ),
}
```

### **128. Read Currency From Header**

This setting controls how the currency is determined.

**Effect:**

* **True**: The currency is retrieved from the `x-currency` header. If the `x-currency` value is not found in the `AVAILABLE_CURRENCIES` dynamic setting, the `DEFAULT_CURRENCY` dynamic setting is used.
* **False**: The currency is determined using the `/users/activate-currency/` endpoint. If it is not defined, the `DEFAULT_CURRENCY` dynamic setting is used.

**Note:**

* When this setting is enabled, the `/users/activate-currency/` endpoint becomes inactive.

Key: `READ_CURRENCY_FROM_HEADER`\
Type: Boolean\
Default: False

### **129. Send Invoice Available Notifications**

This setting determines whether notifications are sent to users when an invoice is available. If set to `True`, a notification informing the user that the invoice is available will be sent. If set to `False`, no such notifications will be sent.

Key: `SEND_INVOICE_AVAILABLE_NOTIFICATIONS`\
Type: Boolean\
Default: True

### **130. Throttling Settings**

This setting controls the number of requests. It is used for traffic management and maintaining system stability. By defining different limits for successful and total requests according to needs, a more flexible throttling mechanism can be created.

Scope and default values for controlling **total requests:**

| Scope                              | Count | Duration |
| ---------------------------------- | :---: | :------: |
| `register`                         |   5   |   1800   |
| `login`                            |   5   |   1800   |
| `register-with-loyalty`            |   5   |   1800   |
| `password-reset`                   |   3   |    60    |
| `send-message`                     |   10  |    60    |
| `user-unsubscribe`                 |   10  |   1800   |
| `create-order-request`             |   10  |   1800   |
| `retail-store-stock`               |   10  |   1800   |
| `cancellation-request-bulk-create` |   1   |     5    |
| `basket`                           |   10  |    60    |
| `create-address`                   |   5   |    60    |
| `user-permissions`                 |   10  |    60    |
| `appointment-date`                 |   10  |    60    |
| `user-segment`                     |   3   |    60    |

Scope and default values for controlling **successful requests:**

| Scope                 | Success | Duration |
| --------------------- | :-----: | :------: |
| `successful-register` |    3    |   1800   |
| `profile-update`      |    5    |   1800   |

Basarili istekleri kontrol eden scope ve varsayılan değerleri:

**Format:**

```py
{
  "scope_key": {    "count": 1, # Quantity
    "duration": 2, # Seconds  }
}
```

**Note:** If the scope is for successful requests, `success` should be used instead of `count`.

Key: `THROTTLING_SETTINGS`\
Type: Object\
Default:

```py
{
    'register': {
        'count': 5,
        'duration': 30 * 60
    },
    'successful-register': {
        'success': 3,
        'duration': 30 * 60
    },
    'login': {
        'count': 5,
        'duration': 30 * 60,
    },
    'register-with-loyalty': {
        'count': 5,
        'duration': 30 * 60,
    },
    'profile-update': {
        'success': 5,
        'duration': 30 * 60
    },
    'password-reset': {
        'count': 3,
        'duration': 60
    },
    'send-message': {
        'count': 10,
        'duration': 60
    },
    'user-unsubscribe': {
        'count': 10,
        'duration': 30 * 60,
    },
    'create-order-request': {
        'count': 10,
        'duration': 30 * 60,
    },
    'retail-store-stock': {
        'count': 10,
        'duration': 30 * 60
    },
    'cancellation-request-bulk-create': {
        'count': 1,
        'duration': 5,
    },
    'basket': {
        'count': 10,
        'duration': 60,
    },
    'create-address': {
        'count': 5,
        'duration': 60,
    },
    'user-permissions': {
        'count': 10,
        'duration': 60,
    },
    'appointment-date': {
        'count': 10,
        'duration': 60,
    },
    'user-segment': {
        'count': 3,
        'duration': 60
    },
}
```

### **131. Checkout Amount Control by Basket**

This setting controls whether the payment process checks only the basket amount or includes additional charges.

**Effect:**

* **True:** Payment is blocked if the basket total is 0. Only the basket items are considered.
* **False:** Payment is blocked only if the total amount, including basket items and additional charges such as shipping, gift wrap, etc., is 0.

Key: `CHECKOUT_AMOUNT_CONTROL_BY_BASKET`\
Type: Boolean\
Default: True

### **132. Email BCC and CC**

This setting enables dynamic configuration of BCC and CC email addresses for specific email templates.

**Effect:**

* Allows adding `bcc` and `cc` fields to outgoing emails per template.
* Default values are defined based on Email Templates with empty arrays.

Key: `EMAIL_BCC_AND_CC`\
Type: Object\
Default:

```
{
    "emails/loyalty/applied-loyalty-money": {
        "bcc": [],
        "cc": []
    },
    "emails/accounts/contact-us": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/offer-accepted": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/order-checkout-url": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/order-ready-for-pickup": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/cargo": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/completed": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/payment-approved": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/payment-failed": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/easy-refund-request": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/order-delivered": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/partial-cargo": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/partial-delivered-cargo": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/completed-subject": {
        "bcc": [],
        "cc": []
    },
    "emails/accounts/password-update-success-subject": {
        "bcc": [],
        "cc": []
    },
    "emails/accounts/contact-us-subject": {
        "bcc": [],
        "cc": []
    },
    "emails/users/conversation-replied": {
        "bcc": [],
        "cc": []
    },
    "emails/users/conversation-replied-subject": {
        "bcc": [],
        "cc": []
    },
    "emails/users/review-rejected": {
        "bcc": [],
        "cc": []
    },
    "emails/users/review-rejected-subject": {
        "bcc": [],
        "cc": []
    },
    "emails/users/question-rejected": {
        "bcc": [],
        "cc": []
    },
    "emails/users/question-rejected-subject": {
        "bcc": [],
        "cc": []
    },
    "emails/orders/package-created": {
        "bcc": [],
        "cc": []
    },
    "emails/accounts/password-update-success": {
        "bcc": [],
        "cc": []
    }
}
```

Example:

```
"emails/orders/order-delivered": {
  "bcc": ["bcc1@akinon.com", "bcc2@akinon.com"],
  "cc": ["cc1@akinon.com", "cc2@akinon.com"]
}
```

### **133. Landing Page Attributes**

Defines which product attributes should automatically generate landing pages. For each value of the attributes in this list (e.g. brand, colour), an existing landing page is used if available; otherwise one is automatically created.

Key: `LANDING_PAGE_ATTRIBUTES`\
Type: list (list of strings)\
Validation: Must be a list\
Default: `[]` (no landing pages are automatically generated)

**Business rule:**

* `["brand", "color"]` → A separate landing page is generated for each brand and each colour value
* When left empty, no landing pages are generated for any attribute

**SEO impact:**

* When configured correctly, SEO-friendly pages are created for facets like brand, colour, material, etc.
* Adding too many attributes causes unnecessary page proliferation (content bloat)
* Adding too few misses long-tail keyword opportunities

**Important behaviour:**

* When an attribute value is created or updated, the landing page is automatically checked and created if needed
* Landing page creation errors do not block the product attribute operation; the error is logged and processing continues

> **Note:** The values in the list must match `key` fields in the `ProductAttribute` model.

**Example:**

```json
["brand", "color", "material"]
```

### **134. Bundle Type Configuration**

Defines bundle types that cannot coexist in the same basket. When one of the defined incompatible pairs is already in the basket, adding the other is blocked.

Key: `BUNDLE_TYPE_CONFIGURATION`\
Type: dict\
Validation: Validated by `BundleTypeConfigurationSerializer`\
Default:

```json
{
  "INCOMPATIBLE_BUNDLE_TYPES": [],
  "ATTRIBUTE_NAME": "bundle_type"
}
```

**Business rule examples:**

* `("premium_bundle", "basic_bundle")` → A customer cannot add both a premium and basic bundle to the same basket
* `("subscription", "one_time")` → Subscription products and one-time purchase products cannot be in the same order
* When left empty, no bundle compatibility checks are performed

**Structure:**

| Field                       | Type         | Required | Description                                                                                                                                                                                |
| --------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `INCOMPATIBLE_BUNDLE_TYPES` | `list[list]` | No       | Pairs of bundle types that cannot coexist. Each element must be a 2-element list. The values in each pair correspond to the possible values of the `ATTRIBUTE_NAME` attribute on products. |
| `ATTRIBUTE_NAME`            | `string`     | No       | Name of the attribute that carries the bundle type (default: `"bundle_type"`). Products must have this attribute set to one of the values referenced in `INCOMPATIBLE_BUNDLE_TYPES`.       |

**Important behaviour:**

* The check is bidirectional: if `["A", "B"]` is defined, both adding B when A is present and adding A when B is present are blocked
* When an incompatible product is added, an error is returned and the product is not added to the basket
* Misconfiguration may allow invalid product combinations that can cause order processing issues
* This setting should be used in conjunction with the `bundle_type_compatibility_condition` basket service condition
* **`null` is a valid bundle type value:** Products that have no `bundle_type` attribute defined are represented as `null`. For example, `["premium_bundle", null]` prevents products without a `bundle_type` attribute from coexisting in the basket with `premium_bundle` type products.

**Example:**

```json
{
  "INCOMPATIBLE_BUNDLE_TYPES": [
    ["premium_bundle", "basic_bundle"],
    ["subscription", null]
  ],
  "ATTRIBUTE_NAME": "bundle_type"
}
```

### **135. Special Page Extraction Strategy**

Determines the default extraction strategy for product listings on special pages. If a specific strategy is assigned to the special page object itself, that takes priority over this setting.

Key: `SPECIAL_PAGE_EXTRACTION_STRATEGY`\
Type: string (choice)\
Validation: Must be one of the valid strategies listed in `SEARCH_PRODUCT_EXTRACTION_STRATEGY`\
Default: `"omnishop.search.strategies.DefaultProductExtractionStrategy"`

**Priority order:**

1. Strategy assigned to the special page object (if present, this is used)
2. This dynamic setting value (used as fallback)

**Valid options:** Same as `SEARCH_PRODUCT_EXTRACTION_STRATEGY` (see setting #86 for the full strategies table).

**Example:**

```json
"omnishop.search.strategies.ListableFirstProductExtractionStrategy"
```

### **136. Tax Client Configuration**

Defines the connection settings for the external tax microservice used to calculate destination-based sales tax (e.g. US state tax) per basket item during checkout. When `enabled` is `true`, the system calls the microservice whenever the shipping address or basket contents change. If the microservice is unavailable or returns an unexpected response, checkout proceeds without tax — the integration is non-blocking.

**Usage:** Read by `omnishop.orders.tax.service.TaxService` via `dynamic_settings.TAX_CLIENT_CONF`. Tax is calculated after offer/discount application and stored per basket item. The result is included in the pre-order context and carried over to order items on order creation.

Key: `TAX_CLIENT_CONF`\
Type: object\
Default: `{"enabled": false}`

**Fields:**

| Field           | Type    | Required         | Description                          |
| --------------- | ------- | ---------------- | ------------------------------------ |
| `enabled`       | Boolean | Yes              | Enables or disables tax calculation. |
| `base_url`      | String  | Yes (if enabled) | Base URL of the tax microservice.    |
| `auth.username` | String  | Yes (if enabled) | Username for HTTP Basic Auth.        |
| `auth.password` | String  | Yes (if enabled) | Password for HTTP Basic Auth.        |

**Example:**

```json
{
    "enabled": true,
    "base_url": "https://tax-service.example.com/",
    "auth": {
        "username": "xxx",
        "password": "xxx"
    }
}
```

### **137. Gift Card Configuration**

Defines the behavioural parameters for the gift card payment feature. Controls whether multiple cards can be used per order, the maximum redeemable amount, how long the balance cache is retained, the OTP re-send cooldown, and the timeout before an orphaned gift card purchase is automatically voided.

Key: `GIFT_CARD_CONFIG`\
Type: object (dict)\
Default:

```json
{
  "multi_card_enabled": false,
  "max_amount_per_order": 0,
  "balance_cache_ttl": 1800,
  "otp_resend_cooldown": 60,
  "void_task_countdown": 1800
}
```

**Structure:**

| Field                  | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                              |
| ---------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `multi_card_enabled`   | `boolean` | `false` | Allows more than one gift card to be applied to a single order. When `false`, a second card addition request is rejected if a card is already present. Set to `true` to enable partial payment across multiple cards.                                                                                                                                    |
| `max_amount_per_order` | `integer` | `0`     | Maximum total amount (in the order's currency) that can be paid with gift cards per order. `0` means unlimited. Enforced both when a card is applied and when the amount is updated; the combined total of all applied cards must not exceed this value.                                                                                                 |
| `balance_cache_ttl`    | `integer` | `1800`  | Duration in seconds that a card balance queried from the provider is kept in cache. When the TTL expires, the reservation is automatically removed on the amount-update screen and the user must re-add the card. Setting this too low on OTP-based flows may cause the cache to expire between OTP verification and the amount page, dropping the card. |
| `otp_resend_cooldown`  | `integer` | `60`    | Minimum number of seconds a user must wait before requesting a new OTP in flows that require OTP verification. Requests made before this cooldown expires are rejected.                                                                                                                                                                                  |
| `void_task_countdown`  | `integer` | `1800`  | Delay in seconds before a scheduled background task automatically voids a gift card purchase when an order could not be created (server error, timeout, etc.). The task is a no-op if the order was successfully created; it only cleans up orphaned transactions.                                                                                       |

**Important behaviour:**

* When `multi_card_enabled` is `false` and a card is already in the basket, any attempt to add a second card returns an error without modifying the basket state.
* When `max_amount_per_order` is greater than `0`, it acts as a ceiling for the combined gift card amount across all applied cards; the order's remaining balance must be covered by another payment method if the ceiling is reached.
* `balance_cache_ttl` should be set high enough to cover the full gift card application flow (OTP verification → amount confirmation). A value lower than the expected user interaction time will result in unexpected card drops.
* The `void_task_countdown` is a safety net for orphaned transactions only; it does not affect normal order creation flows.

**Example:**

```json
{
  "multi_card_enabled": true,
  "max_amount_per_order": 500,
  "balance_cache_ttl": 3600,
  "otp_resend_cooldown": 120,
  "void_task_countdown": 3600
}
```

### **138. Disabled Email Templates**

Controls which system email templates are prevented from being sent. Each key is a template path (without file extension) and each value is a boolean; setting a value to `true` disables that email, `false` keeps it enabled. If a key is omitted, the template's built-in default is used — all templates default to enabled except `emails/orders/preparing`, `emails/orders/payment-approved` and `emails/orders/payment-failed` which default to disabled. All available keys and their defaults are listed in the table below.

Key: `DISABLED_EMAIL_TEMPLATES`\
Type: Object

**Available keys and their defaults:**

| Key                                         | Default |
| ------------------------------------------- | ------- |
| `emails/accounts/contact-us`                | `false` |
| `emails/accounts/email-verification`        | `false` |
| `emails/accounts/password-update-success`   | `false` |
| `emails/loyalty/applied-loyalty-money`      | `false` |
| `emails/orders/cargo`                       | `false` |
| `emails/orders/completed`                   | `false` |
| `emails/orders/easy-refund-request`         | `false` |
| `emails/orders/instore-order-completed`     | `false` |
| `emails/orders/offer-accepted`              | `false` |
| `emails/orders/order-checkout-url`          | `false` |
| `emails/orders/order-delivered`             | `false` |
| `emails/orders/order-ready-for-pickup`      | `false` |
| `emails/orders/package-created`             | `false` |
| `emails/orders/partial-cargo`               | `false` |
| `emails/orders/partial-delivered-cargo`     | `false` |
| `emails/orders/payment-approved`            | `true`  |
| `emails/orders/payment-failed`              | `true`  |
| `emails/orders/preparing`                   | `true`  |
| `emails/users/conversation-replied`         | `false` |
| `emails/users/review-rejected`              | `false` |
| `emails/users/question-rejected`            | `false` |
| `account/email/email_change_old_notice`     | `false` |
| `account/email/email_change_revoked_notice` | `false` |

**Example:**

```json
{
    "emails/orders/preparing": false,
    "emails/orders/instore-order-completed": true,
    "emails/users/conversation-replied": true
}
```

In the example above, the order preparing email is **enabled** (overriding its default-disabled state), while InStore order confirmation emails and conversation reply emails are disabled; every other template keeps sending normally.

{% hint style="warning" %}
Keep `emails/users/review-rejected` and `emails/users/question-rejected` at `false`. When a moderator rejects a review or a question, these emails tell the author that it was not published, why, and which rule it broke, as the consumer review regulation requires. Disabling them stops that notification. See [E-mail Templates](https://docs.akinon.com/technical-guides/commerce/e-mail-templates) for both templates.
{% endhint %}

### **139. External Search Extension Config**

Configures one or more external search extensions (e.g. similarity search, embedding store) that the `ExternalSearchService` broadcasts product upsert/delete operations to, and can delegate image-based search to. External search is enabled as a whole only when at least one extension in the list has `enabled` set to `true`.

**Structure:**

The setting is an object with a single `extensions` list. Each item in the list supports:

| Field      | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                          |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`  | `boolean` | `true`  | Whether this extension is loaded and used. `ExternalSearchService.is_enabled()` returns `true` overall only if at least one extension has this set to `true`.                                                                                                                                                                                        |
| `klass`    | `string`  | —       | Dotted import path of the extension client class. Must be one of the registered choices: `omnishop.search.libs.external_search.extensions.similarity_search.client.SimilaritySearchExtensionClient` (Similarity Search) or `omnishop.search.libs.external_search.extensions.embedding_store.client.EmbeddingStoreExtensionClient` (Embedding Store). |
| `username` | `string`  | —       | Username used to authenticate with the extension's backend.                                                                                                                                                                                                                                                                                          |
| `password` | `string`  | —       | Password used to authenticate with the extension's backend.                                                                                                                                                                                                                                                                                          |
| `host`     | `string`  | —       | Base host/URL of the extension's backend service.                                                                                                                                                                                                                                                                                                    |
| `limit`    | `integer` | `20`    | Result limit passed to the extension (e.g. maximum matches returned by an image search request).                                                                                                                                                                                                                                                     |
| `kwargs`   | `object`  | `{}`    | Additional keyword arguments merged into the extension's configuration, for extension-specific options.                                                                                                                                                                                                                                              |

**Where it is used:**

* **omnishop.search.libs.external\_search.service.ExternalSearchService** — `_load_extensions()` reads `config["extensions"]`, skips any entry with `enabled` falsy or missing `klass`, imports the `klass`, and instantiates it with the top-level config merged with the entry's own config (the entry's keys take precedence). `upsert_products()` and `delete_products()` broadcast to every loaded extension; `search_product_by_image_url()` and `search_product_by_b64_image()` delegate to the first extension that implements them.
* `is_enabled()` is used as a guard — if no extension has `enabled: true`, instantiating `ExternalSearchService` raises `NotImplementedError`.

Key: `EXTERNAL_SEARCH_EXTENSION_CONFIG`\
Type: Object\
Default:

```json
{
    "extensions": []
}
```

**Example:**

```json
{
    "extensions": [
        {
            "enabled": true,
            "klass": "omnishop.search.libs.external_search.extensions.similarity_search.client.SimilaritySearchExtensionClient",
            "username": "search-user",
            "password": "search-password",
            "host": "https://similarity-search.example.com",
            "limit": 20,
            "kwargs": {}
        }
    ]
}
```

### **140. Credit Card Confirmation Attempt Limit**

Tiered rate limit on failed credit card confirmation attempts during checkout. Each tier is evaluated independently, so both quick bursts and slower, sustained abuse are caught. Once any tier's attempt count reaches its `limit` within its `duration`, further confirmation attempts are blocked until the tier's cache entry expires.

By default, attempts are counted per checkout session. A tier can also count attempts by IP address, card BIN or user. This stops attackers who open a new session for every attempt, for example in card testing attacks.

**Structure:**

The setting is a list of tier objects, each with:

| Field      | Type                         | Description                                                                                                                        |
| ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `duration` | `integer` (seconds, min `1`) | The rolling time window for this tier.                                                                                             |
| `limit`    | `integer` (min `1`)          | Maximum number of failed attempts allowed within `duration`. Reaching this count blocks further attempts until the window expires. |
| `scope`    | `string` (optional)          | What the attempts are counted by. One of `session`, `ip`, `bin`, `user`. Defaults to `session`.                                    |

**Scopes:**

| Scope     | Counted by                                                                                     | Counts 3D Secure redirects | Reset on successful order |
| --------- | ---------------------------------------------------------------------------------------------- | -------------------------- | ------------------------- |
| `session` | Checkout session                                                                               | Yes                        | Yes                       |
| `user`    | Logged-in user. Guest checkouts are counted by e-mail address.                                 | Yes                        | Yes                       |
| `ip`      | Client IP address                                                                              | No                         | No                        |
| `bin`     | First 6 digits of the card number and the basket amount. The full card number is never stored. | No                         | No                        |

**How it works:**

* Before each credit card confirmation, the attempt counts of every scope are checked against their tiers. If any tier's limit has been reached within its window, the confirmation is rejected and the shopper is asked to try again later. The same error is returned whichever scope blocks the attempt.
* `session` and `user` count an attempt both when the card fails and when the card is redirected to 3D Secure. A 3D Secure redirect is not yet a confirmed payment, so it still counts. This prevents the limit from being bypassed by repeatedly submitting cards that pass basic checks but never complete payment. Their counts are reset once an order is successfully placed.
* `ip` and `bin` count only failed attempts. Their counts are never reset on success, because they also include attempts of other shoppers.
* A scope without any tier is disabled. Tiers without `scope` belong to the `session` scope, so existing values keep working as before.

{% hint style="warning" %}
Keep the `ip` and `bin` limits loose. Many shoppers can share one IP address, for example behind an office network or a mobile operator. Many shoppers also share the same BIN, for example during a campaign on a single product. Tight limits on these scopes can block real shoppers.
{% endhint %}

Key: `CREDIT_CARD_CONFIRMATION_ATTEMPT_LIMIT`\
Type: List of objects\
Default:

```json
[
    {"duration": 900, "limit": 15},
    {"duration": 3600, "limit": 30},
    {"duration": 21600, "limit": 100}
]
```

The default only has `session` tiers, so the `ip`, `bin` and `user` scopes are disabled until they are added.

**Example:**

```json
[
    {"duration": 900, "limit": 5},
    {"duration": 3600, "limit": 10},
    {"duration": 3600, "limit": 10, "scope": "user"},
    {"duration": 3600, "limit": 50, "scope": "ip"},
    {"duration": 3600, "limit": 20, "scope": "bin"}
]
```

In the example above, a confirmation attempt is blocked when any of these is reached:

* 5 failures within 15 minutes or 10 failures within 1 hour in the same session,
* 10 failures within 1 hour by the same user or guest e-mail address,
* 50 failures within 1 hour from the same IP address,
* 20 failures within 1 hour with the same BIN and basket amount.

### **141. OTP Purpose Settings**

Single source for the one-time password (OTP) knobs, resolved per flow. A *purpose* identifies which flow an OTP belongs to, so a sensitive flow can be made stricter than the rest — for example a smaller wrong-guess budget on login than elsewhere.

Resolution order for each key is: the purpose's own entry, then the shared `default` entry, then the built-in fallback. The `default` entry is the always-present baseline for every flow, and replaces the standalone `SMS_OTP_MAX_VERIFY_ATTEMPTS` setting.

**Structure:**

Keys are `default` (the shared baseline) or a purpose value. Each block accepts:

| Field             | Type                | Fallback when unset               | Description                                                                                                                                                |
| ----------------- | ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_attempts`    | `integer`           | `5`                               | Wrong-guess budget for a single code. On reaching it the challenge is discarded and the customer has to request a new code.                                |
| `expire_time`     | `integer` (seconds) | `SMS_OTP_EXPIRE_TIME` setting     | How long a sent code stays valid. Deliberately not part of the default block, so it keeps following the existing SMS setting unless explicitly overridden. |
| `resent_time_gap` | `integer` (seconds) | `SMS_OTP_RESENT_TIME_GAP` setting | Minimum wait before a new code can be sent for the same challenge. Applies to the SMS channel.                                                             |

**Available purposes:**

| Purpose          | Flow                                                                     |
| ---------------- | ------------------------------------------------------------------------ |
| `login`          | OTP login (`POST /users/otp-login/`)                                     |
| `email-change`   | The identity check before the account's primary email address is changed |
| `phone-change`   | The identity check before the phone number on the profile is changed     |
| `checkout-phone` | A guest proving ownership of the phone number they entered at checkout   |
| `default`        | Shared baseline applied to every flow that has no entry of its own       |

Key: `OTP_PURPOSE_SETTINGS`\
Type: Object\
Default:

```json
{"default": {"max_attempts": 5}}
```

**Example:**

```json
{
    "default": {"max_attempts": 5},
    "login": {"max_attempts": 3, "expire_time": 300, "resent_time_gap": 60}
}
```

In the example above, a login code allows three wrong guesses instead of five, expires after 5 minutes, and cannot be re-requested more often than once a minute. Every other flow keeps the shared baseline.

{% hint style="info" %}
The `login` entry only takes effect when `OTP_LOGIN_VIEW` is set to `EmailOrPhoneOTPLoginRedirectView`, because that is the view which tags its challenges with the `login` purpose. With the default OTP login view the challenge carries no purpose, so only the `default` entry applies to it.
{% endhint %}

### **142. Verification Token Configuration**

Controls the one-time code check that can be required before a customer completes a sensitive action. Each protected action is identified by a *purpose*, and each purpose is switched on and tuned separately, so a project can protect one action without touching the others.

Every purpose is **off by default**. An action is only protected when its own block sets `enabled: true`; the shared `default` block supplies baseline values for the other keys but never switches an action on by itself.

**Protected actions:**

| Purpose          | Action                                                                  | Who it applies to                                 |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------- |
| `email-change`   | Changing the account's primary email address                            | Signed-in customers                               |
| `phone-change`   | Changing the phone number on the profile                                | Signed-in customers                               |
| `checkout-phone` | Proving ownership of the phone number entered at checkout               | **Guests** — signed-in customers are not affected |
| `default`        | Shared baseline for the keys below; does not enable anything on its own | —                                                 |

The first two are *step-up* checks: the customer is already signed in, and the code is a second factor on top of their password. `checkout-phone` is plain verification — there is no account and no password involved, only proof that the number belongs to the person using it.

**Structure:**

Each block accepts only the following keys. Unknown keys, and purposes that are not recognised, are rejected when the setting is saved.

| Field                | Type                        | Default            | Description                                                                                                                                                                                                                                                                                                              |
| -------------------- | --------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`            | `boolean`                   | `false`            | Whether the identity check is required for this action. Must be set inside the action's own block.                                                                                                                                                                                                                       |
| `allowed_channels`   | List of `"sms"` / `"email"` | `["sms", "email"]` | How the customer may choose to receive the code. For a signed-in customer the code goes to the phone number or email address already on the account; for `checkout-phone` it goes to the number the guest just typed, since there is no account to read from. **Ignored for `checkout-phone`**, which is fixed to `sms`. |
| `token_ttl_seconds`  | `integer` (min `1`)         | `600`              | How long the completed check stays valid — in effect, how long the customer has to finish the action after entering the code.                                                                                                                                                                                            |
| `recaptcha_required` | `boolean`                   | `false`            | Whether a passing reCAPTCHA is required before a code is sent. Set per purpose, so an action open to guests can be protected without putting a captcha in front of signed-in customers. The token lifetime comes from `REGISTER_FORM_RECAPTCHA_CONF`, and the keys from `RECAPTCHA_SECRET_KEY`.                          |

The code-level values — how long a code is valid, how many wrong guesses are allowed, and how soon a new code can be requested — are **not** set here. They come from `OTP_PURPOSE_SETTINGS` for the same purpose (section 141 above), so there is one place for each concern.

**See also:** [How to Configure Step-Up Verification](https://docs.akinon.com/tutorials/commerce/how-to-configure-step-up-verification) for the end-to-end setup.

Key: `VERIFICATION_TOKEN_CONF`\
Type: Object\
Default:

```json
{"default": {"enabled": false}}
```

**Example:**

```json
{
    "email-change": {"enabled": true, "allowed_channels": ["email"], "token_ttl_seconds": 900},
    "phone-change": {"enabled": true},
    "checkout-phone": {"enabled": true, "recaptcha_required": true}
}
```

In the example above, an email change requires a code sent to the customer's current email address and they have 15 minutes to finish it; a phone number change is protected too, and the customer may pick either channel with the default 10-minute window. Guests at checkout must verify the phone number they enter, behind a reCAPTCHA.

{% hint style="warning" %}
Restricting `allowed_channels` to a single channel can lock signed-in customers out. For the two step-up actions the check deliberately refuses the channel the customer's current session signed in with — someone who signed in with a text-message code cannot receive the identity code by text message as well. If such an action allows only `sms`, those customers have no way through. The rule does not apply to `checkout-phone`, where the visitor has not signed in at all.
{% endhint %}

{% hint style="danger" %}
Turning `recaptcha_required` on without a configured `RECAPTCHA_SECRET_KEY` blocks the action entirely: every attempt to send a code is rejected as a failed reCAPTCHA. Set the key first, then the flag.
{% endhint %}

{% hint style="info" %}
There is no key for opening an action to guests. Which purposes accept visitors who are not signed in is fixed in code — today `checkout-phone` alone — because the others rely on a phone number or email address already held on the account. For the same reason `checkout-phone` is locked to `sms`: verifying a number means nothing if the code went somewhere else.

See [How to Verify Guest Phone Numbers at Checkout](https://docs.akinon.com/tutorials/commerce/how-to-verify-guest-phone-numbers-at-checkout) for that flow.
{% endhint %}

{% hint style="warning" %}
Turning the identity check on for `email-change` is only half of the setup, and a half-finished setup is permissive rather than broken. The endpoints also have to be routed to their protected variants through the `EMAIL_CHANGE_VIEW` and `EMAIL_SET_PRIMARY_VIEW` environment variables (entries 94 and 95 of [Environment Variables](https://docs.akinon.com/technical-guides/commerce/environment-variables)). With the purpose enabled but the views unrouted, the change still succeeds on the password alone and no undo link is ever sent. A phone number change needs no environment variable.
{% endhint %}

### **143. Secure Email Change Revoke Window**

How many days the one-click undo link sent to a customer's **previous** email address keeps working after their email address is changed.

When a change completes, the old address receives a message with a link that restores it. That is the recovery path for a customer whose account was taken over: the message goes to the address that was taken away from them, which is the one place an attacker no longer controls. This setting bounds how long the link works; afterwards, and once it has been used, the change can no longer be undone.

Using the link does more than restore the address: because the change is assumed to have been someone else's, the account's current password is made unusable and a password reset link is mailed to the restored address. Signed-in sessions are left alone — the unusable password is what stops the attacker from signing in again.

Relevant only when the email change flow is routed to its protected variant through the `EMAIL_SET_PRIMARY_VIEW` environment variable (entry 95 of [Environment Variables](https://docs.akinon.com/technical-guides/commerce/environment-variables)) — that is what sends the message and issues the link. The wording of the message and the values available to it are documented in [E-mail Templates](https://docs.akinon.com/technical-guides/commerce/e-mail-templates); the flow as a whole in [How to Configure Step-Up Verification](https://docs.akinon.com/tutorials/commerce/how-to-configure-step-up-verification).

Key: `SECURE_EMAIL_CHANGE_REVOKE_WINDOW_DAYS`\
Type: Integer (days)\
Default: `7`

**Example:**

```json
14
```

In the example above, a completed email change can be undone from the old address for two weeks.

{% hint style="info" %}
Choose a window long enough for a customer who does not read that inbox daily to notice the message and act on it. The link is single-use in any case.
{% endhint %}

### **144. Secure Phone Change Revoke Window**

How many days the one-click undo link sent by text message to a customer's **previous** phone number keeps working after their phone number is changed.

Unlike an email change there is no confirmation step — a new phone number takes effect as soon as it is accepted — so this link is the only way to undo it. It is single-use, and it is also refused if the number has changed again in the meantime, so a later legitimate change is never overwritten by an older link.

As with an email change, using the link also makes the account's current password unusable and sends a password reset link — by text message, to the restored number. The message templates are documented in [E-mail Templates](https://docs.akinon.com/technical-guides/commerce/e-mail-templates), and the flow in [How to Configure Step-Up Verification](https://docs.akinon.com/tutorials/commerce/how-to-configure-step-up-verification).

{% hint style="danger" %}
The reset text message is delivered only if your project ships an `sms/account/reset-password.html` template. No SMS bodies come with the platform, and a missing one is skipped without an error — so the customer's password would be disabled with no reset link reaching them on that channel. Confirm the template exists before enabling the identity check for phone number changes.
{% endhint %}

Relevant only while the `phone-change` purpose is enabled in `VERIFICATION_TOKEN_CONF`: the message and its undo link ride on the same switch as the identity check, there is no separate setting for them.

Key: `SECURE_PHONE_CHANGE_REVOKE_WINDOW_DAYS`\
Type: Integer (days)\
Default: `7`

**Example:**

```json
3
```

In the example above, a completed phone number change can be undone from the old number for three days.

### **145. Redirect Pages to Pretty URL**

Controls which page types redirect (302) from their internal detail URL to the canonical pretty URL. Each key maps to a page type; set it to `true` to enable the redirect for that type.

| Key            | View              | Internal URL          |
| -------------- | ----------------- | --------------------- |
| `special_page` | `SpecialPageView` | `/special-page/<pk>/` |
| `landing_page` | `LandingPageView` | `/landing-page/<pk>/` |

**Usage:** Checked in `omnishop.cms.resources.views.RedirectionToPrettyUrlMixin.get_pretty_url_redirect()`. If the page object has a `pretty_url` assigned and the resolved canonical URL differs from the current request path, an `HttpResponseRedirect` (302) is returned.

Key: `REDIRECT_PAGES_TO_PRETTY_URL`\
Type: object\
Default: `{"special_page": false, "landing_page": false}`

**Example:**

```json
{
    "special_page": true,
    "landing_page": false
}
```

### **146. Autocomplete Group Size**

Sets how many entries each autocomplete suggestion group returns. The `/autocomplete/` response is split into a product group and a category group, and this setting caps both of them independently.

The value drives the Elasticsearch `size` of the autocomplete query and the category slice, so each additional entry costs one more product, price and thumbnail lookup per keystroke. Keep it as low as the storefront actually renders.

**Effect:**

* Product suggestions are limited to this many entries.
* Category suggestions are limited to this many entries.
* A group returns fewer entries when there are fewer matches; the value is an upper bound, not a fixed count.

Key: `AUTOCOMPLETE_GROUP_SIZE`\
Type: Integer\
Default: 4\
Allowed range: 1–20

**Example:**

```json
6
```

### **147. Product Kind Attribute Name**

Product attribute key that carries the product's "kind" (for example `phone`, `tablet`, `computer`, `gold`). Some payment gateways price or classify a basket by the kind of goods it contains, so they need to know which attribute on the product holds that information. Set this to the attribute key your catalogue actually uses; the attribute value itself still has to match the value the gateway expects.

**Usage:** Read as `dj_dynamic_settings.PRODUCT_KIND_ATTRIBUTE_NAME` and used as a lookup key on `product.attributes`:

* `omnicore.libs.payment_gateways.compay.ComPayCreditGateway._get_basket_type()` — maps the kind of the basket items to a ComPay basket type code.
* `omnishop.payments.strategies.RedirectionPaymentStrategy.get_products()` — sends a `product_kind` per basket item to the gateway.
* `omnishop.payments.extension_services.garantipay.GarantiService._get_basket_items()` — sends a `product_kind` per basket item to GarantiPay.

A product that does not carry the attribute is sent without a kind, which the gateways treat as an unclassified item.

Key: `PRODUCT_KIND_ATTRIBUTE_NAME`\
Type: string\
Default: `"product_kind"`\
Allowed length: 1–64 characters

**Example:**

```json
"product_kind"
```

### **148. Block Guest User From Subscribe**

Controls whether guest users can be subscribed to the newsletter. When `true`, a user whose type is guest is never handed to the subscription gateway, so guest checkouts do not create newsletter records. When `false`, guests are treated like any other user and the remaining subscription rules apply.

This only affects the guest check. Other conditions still run independently — for example, when the `ALLOW_VERIFIED_EMAILS_TO_SUBSCRIBE` setting is active, a user without a verified email address is rejected regardless of this setting.

**Usage:** In `omnishop.users.service.UserSubscriptionService.is_user_subscribable()`: `dj_dynamic_settings.BLOCK_GUEST_USER_FROM_SUBSCRIBE` is checked first, and if it is `true` and `user.is_guest()`, the method returns `False` so no subscription task is queued for that user.

Key: `BLOCK_GUEST_USER_FROM_SUBSCRIBE`\
Type: boolean\
Default: `false`

**Example:**

```json
true
```

### **149. Autoselect Shipping**

When `true`, the shipping option page selects the option for the customer instead of showing it, provided exactly one option is available after all shipping rules and filters have been applied. The page is then reported as already completed and the checkout moves on to the next step. When `false`, the customer always sees the shipping option page and has to confirm the single option manually.

Applies to `ShippingOptionSelectionPage` and to `RemoteShippingOptionSelectionPage`, which inherits it. The data-source and attribute-based shipping pages implement their own completion logic and are not affected by this setting.

**Usage:** In `omnishop.orders.pages.shipping_option.ShippingOptionSelectionPage.is_already_done()`: when the pre-order has no shipping option yet, `dj_dynamic_settings.AUTOSELECT_SHIPPING` is checked; if it is `true` and exactly one available shipping option remains, that option is written to the pre-order and the method returns `True`.

Key: `AUTOSELECT_SHIPPING`\
Type: boolean\
Default: `false`

**Example:**

```json
true
```

### **150. OrdersRefundableStartDateField**

Selects the date field the refund window is measured from. `ORDERS_REFUNDABLE_DAYS` defines how long an order item stays refundable; this setting defines when that countdown starts. By default the countdown starts at order creation, so an item shipped late loses part of its return window. Point the setting at the shipment or delivery date to start the countdown when the customer actually receives the item. When `ORDERS_REFUNDABLE_DAYS` is empty, no time-based check runs and this setting has no effect.

The setting is evaluated per order item. When the selected field is empty on an item — for example an item that never reached a delivered status — the countdown falls back to the creation date, so refund eligibility is never left undefined.

Key: `ORDERS_REFUNDABLE_START_DATE_FIELD`\
Type: string (choice)\
Validation: Must be one of the values below\
Default: `created_date`

**Choices**

* `created_date` — the return window starts when the order is placed (default).
* `shipped_date` — the return window starts when the item is handed to the carrier.
* `delivered_date` — the return window starts when the item is delivered to the customer.

**Example**

```json
"delivered_date"
```

> **Note:** The product attribute `is_refundable` takes precedence over this setting. When a product carries `is_refundable` as false, its items are never refundable and no date calculation runs. Products without the attribute are treated as refundable.

### **151. Basket Offer Exclude Cancelled Orders**

When `true`, cancelled orders are excluded when checking whether a user has reached the `max_usage_per_user` limit on a basket offer (voucher code or coupon). This allows users to reuse a voucher code after cancelling an order that was placed with that code.

**Effect:**

* **True:** Cancelled orders are not counted toward the per-user usage limit. A user can reuse the voucher code after cancelling.
* **False:** Cancelled orders count toward the limit. Once a user places an order with the code (even if later cancelled), that usage is counted.

Key: `BASKET_OFFER_EXCLUDE_CANCELLED_ORDERS`\
Type: Boolean\
Default: False

### **151. Allow Anonymous Access To Registered Orders**

When `true`, orders of registered users can be looked up, cancelled and returned without signing in, by order number and email address. When `false`, only orders of guest users are accepted.

**Effect:**

* **True:** `/users/orders/anonymous/`, `/users/orders/anonymous/cancellation_requests/`, `/users/orders/anonymous/bulk_cancellation_requests/` and the guest flow of `/orders/{order_number}/cancel/` accept orders of both guest and registered users. The email address must still match the one on the order.
* **False:** These endpoints accept only orders of guest users. An order of a registered user returns `400` as if it did not exist.

**Where it is used**

* **omnishop.users.resources.serializers** — `AnonymousOrderQuerySerializer` limits the `order` field to orders of guest users; when `ALLOW_ANONYMOUS_ACCESS_TO_REGISTERED_ORDERS` is `true`, it accepts all orders.

Key: `ALLOW_ANONYMOUS_ACCESS_TO_REGISTERED_ORDERS`\
Type: Boolean\
Default: False

> **Note:** Enabling this setting lets anyone who knows an order number and its email address view and cancel a registered user's order without a password. Enable it only when the brand explicitly requires order tracking without signing in for all orders.

### **152. Autocomplete Product Attributes**

Lists the product attributes returned with each product suggestion of the `/autocomplete/` response. Use it to give the storefront the brand and category of the suggested products, for example for `view_item_list` and `select_item` analytics events.

**Effect:**

* The values are returned under `extra.attributes` of each product suggestion, keyed by attribute key.
* Single-value attributes with an option label, such as dropdowns, return the label in the request language (for example `Damas` instead of the stored option value).
* Multi-value attributes return the list of stored option values, not their labels.
* Other attributes return their stored value, translated for localizable attributes.
* An attribute the product does not have is returned as `null`.
* **Empty list:** `extra.attributes` is an empty object `{}`; the rest of the response is unchanged.

Key: `AUTOCOMPLETE_PRODUCT_ATTRIBUTES`\
Type: List of strings\
Default: `[]`

**Example:**

```json
["integration_marka", "integration_kategori"]
```

### **153. Review Requires Purchase**

Controls whether a customer can review an order item only after it has been delivered. A review is always written from one of the customer's own order items and carries a 1–5 star rating; this setting decides whether that order item must also be in the delivered status.

**Effect:**

* **True:** A review is accepted only when the order item it names is currently in the delivered status (`550`). An order item that is bought but not yet delivered, for example one that is still on its way, and one that has since been refunded (`600`) do not qualify; the storefront receives `400` with `{"non_field_errors": ["Only a customer who received this product can review it."]}`.
* **False:** The delivery check is skipped, so a customer can review an order item of theirs that has not been delivered yet.

**Important behaviour:**

* A review of an order item from someone else's order is refused at both values.
* Any earlier review on the same order item that was not rejected (pending, approved, or created before moderation was introduced) blocks a second one; after a rejection, the customer may write a new one.
* Only reviews created from the storefront are affected. Questions and private messages ignore this setting, and reviews cannot be created from the panel at any value.

Key: `REVIEW_REQUIRES_PURCHASE`\
Type: Boolean\
Default: `true`

**Example:**

```json
false
```

In the example above, customers can review an order item as soon as they have bought it, before it is delivered.

{% hint style="info" %}
Despite its name, this setting is about delivery, not purchase. When it is `false`, only the delivery requirement is lifted: the order item must still belong to the customer, and the one-review-per-purchase rule still applies.
{% endhint %}

### **154. Social Login Activate Inactive User**

Controls whether an existing customer who is inactive (the user status is passive in Omnitron) is activated when they sign in with a social account such as Google or Apple.

**Effect:**

* **True:** When an inactive customer signs in with a social account, the customer is activated and the sign-in completes. This applies to every social login provider and to both the web flow and the sign-in with a token (mobile).
* **False:** An inactive customer cannot sign in with a social account. The sign-in is stopped and the customer is redirected to the login URL of Commerce.

**Important behaviour:**

* The customer is activated only when the social login provider reports the customer's e-mail address as verified.
* Anonymized customers are never activated.
* A customer is not activated when another active customer has the same e-mail address or phone number.
* Only sign-ins activate a customer. Connecting a social account to a signed-in customer does not activate another customer.
* Each activation is recorded as an audit event with the event type `social_login_user_activated`. The event keeps the social login provider, the account ID at the provider, the e-mail address, and the time, URL, and IP address of the sign-in. Use the `/audit-events/` data warehouse endpoint to find when and how a customer was activated. A customer is activated only together with this audit event.

Key: `SOCIAL_LOGIN_ACTIVATE_INACTIVE_USER`\
Type: Boolean\
Default: `false`

**Example:**

```json
true
```

In the example above, an inactive customer who signs in with Google is activated and signed in.

{% hint style="warning" %}
A customer who was made inactive on purpose (for example, from Omnitron) is also activated again when they sign in with a social account. Enable this setting only when inactive customers should be able to return through social login.
{% endhint %}

### **155. SendOrderCancelledNotificationsPartially**

When `true`, order cancellation notifications can be sent per order item as each item is cancelled (partial cancellation). When `false`, a single order cancellation notification is sent once, only when the full order transitions to `cancelled`.

**Where it is used**

* **omnishop.orders.actions** — `send_order_cancelled_notifications` is registered on `order_update_actions` and runs only when `not dynamic_settings.SEND_ORDER_CANCELLED_NOTIFICATIONS_PARTIALLY` and the order status transitions to `cancelled`; it sends a single notification for the order with all of its items. `send_order_item_cancelled_notifications` is registered on `order_item_update_actions` and runs when `dynamic_settings.SEND_ORDER_CANCELLED_NOTIFICATIONS_PARTIALLY` and an order item's status transitions to `cancelled`.
* Notifications are skipped entirely when the `NOTIFICATION_GATEWAY` setting has no active gateway configured.
* Per-item notifications are deduplicated: once an item has been notified it is marked internally and is skipped on any later run, so it is never reported twice. This matters for batch flows such as sync-cron, where several items of the same order can be cancelled in quick succession.
* Cancellation events for the same order are debounced: repeated triggers for the same order within a 30 second window are coalesced into a single scheduled notification task rather than sending one per trigger.

Key: `SEND_ORDER_CANCELLED_NOTIFICATIONS_PARTIALLY`\
Type: boolean\
Default: False

**Example**

Set to `true` to notify the customer as each item of an order is cancelled; set to `false` (default) to send a single notification once the entire order is cancelled.

### **156. Register Form reCAPTCHA Configuration**

Controls server-side Google reCAPTCHA verification on customer registration and on the code-sending step of OTP sign-in. When it is on, the request must carry a `g-recaptcha-response` token, which Commerce checks with Google before going on. When it is off (the default), no reCAPTCHA is checked on these endpoints.

The value is an object with two fields:

| Field       | Type                | Default | Description                                                                                                                                                                                                                                                                                                 |
| ----------- | ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enable`    | `boolean`           | `false` | Turns the reCAPTCHA check on or off. It cannot be saved as `true` while `RECAPTCHA_SECRET_KEY` is empty.                                                                                                                                                                                                    |
| `token_ttl` | `integer` (min `1`) | `120`   | How many seconds a token that passed verification is remembered. Google accepts each token only once, so without this a customer who resends a code, or fixes a form error and submits again, would have to solve the reCAPTCHA again. Within this window the same token is accepted without asking Google. |

**Where it applies**

* **Registration** (`POST /users/registration/`): the registration views Commerce provides for this endpoint check it — the default one, the KVKK one and the SMS OTP one. The check runs after the request body has passed field validation, so an invalid form is reported first. For the variants that confirm a code, it is checked when a code is sent or resent, not when the customer submits the code. Other registration endpoints, such as `/users/register-with-loyalty/`, do not check it, and neither does a custom view set through the `REST_REGISTER_VIEW` environment variable (entry 70 of [Environment Variables](https://docs.akinon.com/technical-guides/commerce/environment-variables)) unless it includes the check.
* **OTP login** (`POST /users/otp-login/`): only when `OTP_LOGIN_VIEW` is set to `omnishop.users.views.EmailOrPhoneOTPLoginRedirectView`. The default phone-only login does not check reCAPTCHA. It is checked when a code is sent or resent, not when it is verified. Unlike registration, the check runs before the request body is validated, so a bad or missing token is reported before any field errors. See [How to Enable Email Identification for OTP Login](https://docs.akinon.com/tutorials/commerce/how-to-enable-email-identification-for-otp-login).
* **Verification init** (`POST /users/verification/init/`): `enable` is ignored here. Whether a token is required is decided per purpose by `recaptcha_required` in `VERIFICATION_TOKEN_CONF` (section 142); this setting only supplies `token_ttl`.

A request that needs a token and has none, or has one Google rejects, fails with `400 Bad Request` and a `g-recaptcha-response` error. A missing token and a rejected token return the same message. If Google cannot be reached, the request fails with a "Could not verify, please try again" message.

Key: `REGISTER_FORM_RECAPTCHA_CONF`\
Type: object\
Default: `{"enable": false, "token_ttl": 120}`

**Example**

```json
{"enable": true, "token_ttl": 120}
```

The storefront sends the token it got from the reCAPTCHA widget in the request body:

```json
{
    "email": "john.doe@example.com",
    "password": "Test123",
    "confirm": true,
    "g-recaptcha-response": "<token from the reCAPTCHA widget>"
}
```

{% hint style="info" %}
Set `RECAPTCHA_SITE_KEY` and `RECAPTCHA_SECRET_KEY` (sections 44 and 45) first, then turn `enable` on. The site key is used by the storefront to render the widget; the secret key is what lets Commerce verify the token. The check that stops `enable` from being saved without a secret key runs only when this setting is saved: if you empty `RECAPTCHA_SECRET_KEY` later while `enable` is `true`, every request that needs a token fails as a failed reCAPTCHA.
{% endhint %}

{% hint style="warning" %}
`enable` is one switch for both registration and the email-or-phone OTP login, so turning it on for one turns it on for the other if that view is in use. Make sure every storefront form that calls these endpoints sends the token before you enable it, or those requests will start failing with `400`.
{% endhint %}

### **157. Basket Item Attribute Strategy**

Controls which `attributes` a client may set on a basket item when adding a product to the basket. The line reference of a basket item is derived from the product plus its attributes, so a client that sends arbitrary attribute keys can split a single product across several basket lines. That can be abused to over-apply multi-buy / line-based promotions and pay less. This setting selects the strategy that filters incoming attributes at add time.

Bundle products are never filtered by this setting — their attributes are keyed by chapter slug and validated separately.

Key: `BASKET_ATTRIBUTES_STRATEGY`\
Type: string (choice)\
Validation: Must be one of the values below\
Default: `allow`

**Choices**

* `allow` — keep every attribute the client sends (legacy behaviour, no brand risk). This is the default so enabling the setting changes nothing until a stricter strategy is chosen.
* `schema_based` — keep only the keys that belong to the product's own attribute set, plus the keys listed in `BASKET_ATTRIBUTES_ALLOWED_KEYS`. Any other key is dropped, so fabricated keys can no longer create extra lines.
* `deny` — keep no attributes at all (not even the allow-listed system keys). Use only for brands that do not rely on basket item attributes.

**Example**

```json
"schema_based"
```

> **Note:** `schema_based` keeps allow-listed keys such as `gift_note` intact, and a `gift_note` value is still part of the line reference — two items with different gift notes remain distinct lines. `schema_based` blocks fabricated keys, not the line-splitting that legitimately-allowed keys or real product variants produce.

### **158. Basket Item Attribute Allowed Keys**

The set of attribute keys the `schema_based` strategy keeps in addition to the product's own attribute-set keys. This is the single, brand-overridable source of non-schema keys: override it to add brand-specific keys or to remove keys a brand should not accept.

Defaults to the platform's known system keys — the attribute keys the platform itself writes onto basket items — so the default behaviour of `schema_based` does not break gift notes, remote pricing, weight, or bundle image handling. Has no effect while `BASKET_ATTRIBUTES_STRATEGY` is `allow` or `deny`.

Key: `BASKET_ATTRIBUTES_ALLOWED_KEYS`\
Type: array of strings\
Default: `["extra_product_sku", "gift_note", "inquiry", "is_remote_price_set", "needs_bukalemun_image", "tax", "weight_type"]`

**Example — allow one extra brand key on top of the defaults**

```json
["gift_note", "inquiry", "is_remote_price_set", "tax", "needs_bukalemun_image", "weight_type", "extra_product_sku", "engraving"]
```

### **159. Basket Offer Error Conf**

Selects which reasons for rejecting a campaign code get their own error instead of the general "not valid" error. Each reason is a key of the object; a missing key counts as `false`. More keys may be added for other reasons later, and each one is `false` by default, so enabling one reason does not change the others.

**Keys:**

* **max\_usage\_per\_user:** Controls the error a customer receives when they enter the voucher code of an active campaign whose **Maximum Number of Applications (Per Customer)** (`max_usage_per_user`) they have already reached. It applies to voucher codes, coupon codes and bulk voucher codes.
  * **True:** The code is rejected as used before. The basket (`PATCH /baskets/basket/`) returns `406` with `error_code` `basket_voucher_100_2` and the message "This voucher code can only be used once."; the voucher code step of the checkout returns the same message on the `voucher_code` field.
  * **False:** The code is rejected as not valid, the same as a code that does not exist. The basket returns `406` with `error_code` `basket_voucher_100_1` (or the upsell message of the campaign when its conditions are partly met); the checkout returns "Voucher code is not valid".

**Important behaviour:**

* Only the error changes. The discount is never applied once the limit is reached, whatever the value.
* The limit counts the customer's orders that used the campaign. Use `BASKET_OFFER_EXCLUDE_CANCELLED_ORDERS` to leave cancelled orders out of this count.
* A code that does not exist, or whose campaign conditions are not met, keeps the `basket_voucher_100_1` error whatever the value.
* `basket_voucher_100_2` is also returned, whatever the value, for a code that is already marked as used (for example, a used bulk voucher code). The storefront can show one "used before" message for this error code.

Key: `BASKET_OFFER_ERROR_CONF`\
Type: Object\
Default: `{"max_usage_per_user": false}`

**Example:**

```json
{
  "max_usage_per_user": true
}
```

In the example above, a customer who already used a voucher code that can be used once per customer receives `basket_voucher_100_2` when they enter it again, and the storefront can tell them that the code was used before.

### **160. Defer Async Order Notifications**

Controls when the order received notifications of an order with an asynchronous payment are sent. For an asynchronous payment, the payment gateway returns a pending result at checkout, and the order is created with the `payment_waiting` (`300`) status. Commerce then checks the payment status until the payment is approved or rejected.

**Effect:**

* **True:** The order received notifications (the `emails/orders/completed` email, the order completed SMS and notification, the InStore order email and the order created push notification) are not sent at checkout. They are sent when the payment is approved and the order moves to `waiting` (`200`). When the payment is rejected and the order is cancelled, they are never sent, and the customer receives the order cancellation push notification and, when it is enabled, the [Order Payment Failed](https://docs.akinon.com/pages/88cIE2Cv8mT9iU2RGt0K#id-27.-order-payment-failed) email.
* **False:** The order received notifications are sent at checkout, while the payment is still pending.

**Important behaviour:**

* Only orders with an asynchronous payment are affected: the order has the `payment_waiting` status and a successful pre-purchase transaction. Pay later and funds transfer (reference code) orders also wait for the payment, but their notifications are still sent at checkout.
* The notifications are sent once per order, even when the payment result comes both from the payment gateway's notification and from the periodic payment status check.
* The [Order Payment Approved](https://docs.akinon.com/pages/88cIE2Cv8mT9iU2RGt0K#id-26.-order-payment-approved) email (`emails/orders/payment-approved`) is sent on approval independently of this setting, when it is enabled in `DISABLED_EMAIL_TEMPLATES`.

Key: `DEFER_ASYNC_ORDER_NOTIFICATIONS`\
Type: Boolean\
Default: `false`

**Example:**

```json
true
```

In the example above, a customer who pays with an asynchronous payment receives the order received email only after the payment is approved.

{% hint style="warning" %}
The setting is read when the order is created and again when the payment result arrives. If you change it while orders are waiting for their payment, the customers of those orders can receive the order received notifications twice, or not at all.
{% endhint %}


---

# 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://docs.akinon.com/technical-guides/commerce/dynamic-settings.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.
