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

# Special Pages

Administrative endpoints for **special pages** — storefront pages that list the products of a single product collection under their own URL, optionally with a desktop and a mobile banner, a banner link, a description and an embedded video. They are typically used for campaign or brand pages.

Every active special page is reachable on the storefront through a **pretty URL** that is generated from the page's `url`. The pretty URL is created, updated and removed automatically as the page is created, changed, deactivated and deleted; it is returned read-only in the `pretty_url` field.

### Core Capabilities

**1. Special Page Listing & Filtering**

* Retrieve a paginated list of special pages, active and inactive alike.
* Filter by name, URL, template, product collection name, active state, product extraction strategy and creation / modification date.
* Order results with the `sort` parameter.

**2. Special Page Retrieval**

* Retrieve a single special page.
* The `/detailed/` variants of the list and retrieve operations return the product collection as a nested object instead of its identifier.

**3. Special Page Management**

* Create a special page; its pretty URL is generated in the same request.
* Fully or partially update a special page; the pretty URL follows the new `url`.
* Deactivate a special page by setting `is_active` to `false`, which also removes its pretty URL.
* Delete a special page. Deleting is a **soft delete** — the record is kept and marked inactive.

### URL Uniqueness

A create request is rejected with `406` (`special_page_200`) when another special page already uses the same `url`, or when another pretty URL already has that path. The comparison ignores leading and trailing slashes, so `/summer-sale` and `/summer-sale/` are treated as the same path.

Turkish characters (`ç`, `ğ`, `ı`, `İ`, `ö`, `ş`, `ü` and their capitals) are not accepted in `url`.

### Deactivation & Deletion

* Setting `is_active` to `false` on an active page removes its pretty URL; the response then returns `pretty_url` as `null`. Setting it back to `true` generates a new pretty URL.
* `DELETE` marks the page inactive and removes its pretty URL. The record itself stays in the database and is still returned by the list and retrieve operations.

> **Warning:** A special page that still has a pretty URL cannot be deleted directly — the request is rejected with `406` and the page stays active. Deleting the pretty URL on its own is rejected in the same way. Deactivate the page first with a partial update (`{"is_active": false}`), which removes the pretty URL, and then send the `DELETE` request.

### Product Extraction Strategy

`extraction_strategy` decides which variant of a product is shown in the storefront listing of the special page. It must be included in create and full-update requests, but may be `null`; a `null` value means the site-wide default is used (see `SPECIAL_PAGE_EXTRACTION_STRATEGY` under **Dynamic Settings & Environment Variables**).

A request may send either the short name or the full value of a strategy; responses always return the full value.

| Short name             | Full value                                                          | Behavior                |
| ---------------------- | ------------------------------------------------------------------- | ----------------------- |
| `default`              | `omnishop.search.strategies.DefaultProductExtractionStrategy`       | Default                 |
| `first_item`           | `omnishop.search.strategies.FirstItemSearchExtractionStrategy`      | First Variant           |
| `listable_first`       | `omnishop.search.strategies.ListableFirstProductExtractionStrategy` | Listable Variant First  |
| `min_price_first`      | `omnishop.search.strategies.MinPriceFirstProductExtractionStrategy` | Min Price Variant First |
| `max_price_first`      | `omnishop.search.strategies.MaxPriceFirstProductExtractionStrategy` | Max Price Variant First |
| `all_sub_products`     | `omnishop.search.strategies.AllSubProductsExtractionStrategy`       | All Sub Products        |
| `offer_product`        | `omnishop.search.strategies.OfferProductExtractionStrategy`         | Offer Product           |
| `product_sorting_item` | `omnishop.search.strategies.ProductSortingItemExtractionStrategy`   | Product Sorting Item    |

Any other value is rejected with `400` (`No matching type.`).

### Translations

The fields `name`, `banner`, `banner_mobile`, `banner_url`, `banner_description` and `video_embedded_code` are translatable. They are written to, and read from, the language selected for the request:

* In the default language (`LANGUAGE_CODE`) the values are stored on the page itself.
* In any other configured language they are stored as a translation of the page; the default-language values are left unchanged. When no translation exists for the requested language, the default-language value is returned.

The remaining fields (`url`, `template`, `product_collection`, `is_active`, `extraction_strategy`) are shared by all languages. Whether the `Accept-Language` header can select the request language is controlled by `IGNORE_ACCEPT_LANGUAGE_HEADER`.

Two exceptions apply regardless of the request language:

* The `/detailed/` operations always return the default-language values.
* Filters match against the default-language values.

### Language-Specific URLs

On multi-language sites (`PRETTY_URL_MULTI_LANGUAGE` on), `specialpageprettyurl_set` holds a separate URL of the page for each additional language:

* The field is **required** on create and full update; an empty list is accepted.
* Each item carries a `language` and a `url`. The default language cannot be used — its URL is the page's own `url` — and is rejected with `406` (`special_page_100`).
* There is at most one URL per language. Sending a language that already has a URL replaces it; languages that are not included in the request are left unchanged.
* The items are not applied in a request that deactivates the page.

On single-language sites the field is optional and any value sent is ignored.

### Images

`banner` and `banner_mobile` are image uploads, so requests that set them are sent as `multipart/form-data`. In a multipart request, send the items of `specialpageprettyurl_set` as indexed fields — `specialpageprettyurl_set[0]url`, `specialpageprettyurl_set[0]language`, and so on — and send an empty `extraction_strategy` for `null`. Sending `null` for an image in a JSON request removes it.

### Filtering & Ordering

| Parameter                                                      | Match                                                        | Notes                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`, `url`, `template`, `banner_url`, `video_embedded_code` | Case-insensitive partial match                               | Send `NULL_VALUE` to return only pages where the field is empty, or `NOT_NULL_VALUE` for pages where it is set.                                                                                                                                       |
| `extraction_strategy`                                          | Case-insensitive partial match on the full value             | `?extraction_strategy=ListableFirst` matches `omnishop.search.strategies.ListableFirstProductExtractionStrategy`; the short name (`listable_first`) does not match. `NULL_VALUE` / `NOT_NULL_VALUE` select pages without / with an explicit strategy. |
| `product_collection`                                           | Case-insensitive partial match on the **collection name**    | Not the collection identifier.                                                                                                                                                                                                                        |
| `banner_description`                                           | Exact                                                        |                                                                                                                                                                                                                                                       |
| `is_active`                                                    | Exact                                                        | `true` or `false`.                                                                                                                                                                                                                                    |
| `pretty_url`                                                   | Exact                                                        | Identifier of a pretty URL. An identifier that does not exist is rejected with `400`.                                                                                                                                                                 |
| `created_date`, `modified_date`                                | Exact, plus the `__gt`, `__gte`, `__lt` and `__lte` suffixes | Values must be full ISO 8601 date-times (for example `2026-01-01T00:00:00`); a date without a time is rejected with `400`.                                                                                                                            |

Parameters that are not listed here are ignored. Use the `sort` query parameter to order the results; prefix with `-` for descending.

### Dynamic Settings & Environment Variables

**Dynamic settings** (`dj_dynamic_settings`):

| Key                                | Type                                                                                 | Default                                                                                                                               | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IGNORE_ACCEPT_LANGUAGE_HEADER`    | boolean                                                                              | `true`                                                                                                                                | Whether the `Accept-Language` header is discarded before the request is processed. While it is `true`, the header is honored only when the request also carries an `X-Omnitron-Session` header; otherwise the default language is used. Affects **every** operation: the selected language decides which translation of the translatable fields is written by create and update requests and returned by list and retrieve requests (see **Translations**). |
| `SPECIAL_PAGE_EXTRACTION_STRATEGY` | string, one of the full strategy values listed under **Product Extraction Strategy** | `omnishop.search.strategies.DefaultProductExtractionStrategy` (or the `SPECIAL_PAGE_EXTRACTION_STRATEGY` Django setting when defined) | The strategy the storefront uses for pages whose `extraction_strategy` is `null`. It does not change the responses of these endpoints — a page without its own strategy is still returned with `extraction_strategy: null`.                                                                                                                                                                                                                                 |

**Environment variables / Django settings:**

| Setting                     | Default                                                       | Effect                                                                                                                                                                           |
| --------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PRETTY_URL_MULTI_LANGUAGE` | `false` (read from the environment variable of the same name) | Enables language-specific URLs. When on, `specialpageprettyurl_set` is required on create and full update; when off, it is optional and ignored. See **Language-Specific URLs**. |
| `LANGUAGE_CODE`             | `tr-tr`                                                       | The default language. Translatable fields written in this language are stored on the page itself, and this language cannot be used in `specialpageprettyurl_set`.                |
| `LANGUAGES`                 | `tr-tr` only                                                  | The languages the site supports. A language that is not listed here cannot be selected for a request, so translations for it cannot be written or read.                          |


---

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

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

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

```
GET https://apidocs.akinon.com/commerce-openapis/admin/special-pages.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.
