> 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/widgets.md).

# Widgets

Administrative endpoints for **CMS widgets** — named, reusable content blocks that the storefront renders by slug. Each widget belongs to a **widget type** (see **Widget Types**), points to the template used to render it, and carries a set of attribute values whose keys and data types are defined by the widget type's schema.

Product collection widgets are a specialised kind of widget and are managed with their own endpoints; they never appear in, and cannot be read, changed, or deleted through, the endpoints in this section.

### Core Capabilities

**1. Widget Listing & Filtering**

* Retrieve a paginated list of widgets, ordered by identifier by default.
* Filter by name, slug, template, widget type, and creation or modification date, and order results with `sort`.
* Retrieve the same list with each widget's type embedded (`GET /widgets/detailed/`).

**2. Widget Lifecycle Management**

* Create a widget with a unique slug and its attribute values.
* Retrieve a single widget, optionally with its type embedded (`GET /widgets/{id}/detailed/`).
* Fully or partially update a widget, including replacing its attribute values.
* Permanently delete a widget.

### Widget Fields

| Field               | Type             | Description                                                                                                                                                          |
| ------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pk`                | integer          | The unique identifier of the widget. Read-only.                                                                                                                      |
| `created_date`      | date-time        | When the widget was created. Read-only.                                                                                                                              |
| `modified_date`     | date-time        | When the widget was last changed. Read-only.                                                                                                                         |
| `name`              | string (max 255) | A display name. Not unique. Required on create and full update.                                                                                                      |
| `slug`              | string (max 255) | The unique key the storefront uses to look the widget up. Required on create and full update. Normalized before it is stored — see **Slug Rules**.                   |
| `widget_type`       | integer          | The identifier of the widget type. Required on create and full update. The `/detailed/` endpoints return the full widget type object instead.                        |
| `template`          | string (max 512) | The path of the template used to render the widget. Required on create and full update.                                                                              |
| `attributes`        | object           | The widget's attribute values, keyed by the attribute keys defined in the widget type's schema. Optional; defaults to `{}` on create. See **Attributes**.            |
| `attributes_kwargs` | object           | Additional details for attribute values that are not plain values — for example the public `url` of an uploaded image or file. Read-only; derived from `attributes`. |

### Slug Rules

* `slug` may contain only letters, digits, underscores, and hyphens. Spaces or other characters are rejected with `400 Bad Request`.
* The value is **normalized** before it is stored: converted to lower case, with underscores replaced by hyphens — sending `Hero_Banner` stores `hero-banner`.
* `slug` is unique across all widgets, including product collection widgets. Sending a slug that exactly matches an existing one is rejected with `400`. Sending one that only matches after normalization (`Other` when `other` exists) is rejected with `406` and error code `cms_widget_100`, on create and on update alike.
* **On partial update, changing `name` without also sending `slug` regenerates the slug from the new name** — `{"name": "Summer Sale"}` changes the slug to `summer-sale`. Storefront pages that reference the old slug stop finding the widget. Send the current `slug` together with `name` to keep it. If the regenerated slug is already taken, the update is rejected with `406` (`cms_widget_100`) and nothing is changed.

### Attributes

The keys and data types a widget accepts are defined by its widget type's schema. Each schema entry declares a `data_type` (for example `text`, `image`, `dropdown`), whether the attribute takes a list of values (`multi`), and whether it is stored separately per language (`is_localizable`).

* **Every value is validated against its schema entry.** A value of the wrong type, a single value for a `multi` attribute (or a list for a non-`multi` one), or a `dropdown` value outside its choices is rejected with `406` and error code `attribute_input_type_100`.
* **Writing attributes replaces them.** A create, or an update that includes `attributes`, first clears the widget's non-localizable attribute values and its localizable values for the request language, then stores the values sent. Keys you leave out are removed. An update without `attributes` leaves the stored values untouched.
* **Unknown keys** that are not defined in the widget type's schema are silently dropped, on create and on update.
* **Localizable attributes** are stored for the language of the request only. When reading, the response merges the non-localizable values, the default-language values, and the request-language values, with the request language taking precedence.
* Changing `widget_type` does not re-validate the stored values. Send `attributes` in the same request to bring them in line with the new type's schema.
* `attributes` must be a JSON object. An array, a string, or `null` is rejected with `400`. Omitting it on create creates the widget without attribute values.

### Filtering & Ordering

| Parameter                       | Match                                                                                                                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                          | Case-insensitive contains.                                                                                                                                                   |
| `slug`                          | Case-insensitive contains — `?slug=banner` matches `hero-banner`.                                                                                                            |
| `slug__in`                      | Exact match on any of a comma-separated list — `?slug__in=hero-banner,footer`.                                                                                               |
| `template`                      | Case-insensitive contains.                                                                                                                                                   |
| `widget_type`                   | Exact widget type identifier.                                                                                                                                                |
| `created_date`, `modified_date` | Exact ISO 8601 date-time. Add `__gt`, `__gte`, `__lt`, or `__lte` for a range, e.g. `?created_date__gte=2026-01-01T00:00:00Z`. A date without a time is rejected with `400`. |

* Append `!` to a filter name to exclude matching widgets instead — `?slug!=hero-banner`.
* There is no `id` or `pk` filter; use `GET /widgets/{id}/` to read a single widget.
* `sort` accepts any stored widget field, e.g. `?sort=-modified_date` or `?sort=name`. An unrecognised value is ignored and the default order (by identifier) is kept.

### Storefront Caching

The storefront caches widgets by slug for up to about **three minutes**. After a widget is updated or deleted, storefront pages may keep showing the previous version until the cache expires. The administrative endpoints in this section always read the current data.

### Audit Logging

Every create, update, and delete is recorded in the audit event log together with the request body, the requesting user, and the client details.

### Deletion Behavior

Deleting a widget is a **hard delete** — the record is permanently removed from the database. Storefront pages refer to a widget by slug, and a slug that no longer exists simply renders nothing.

A widget that is used by a **data source landing page** cannot be deleted: the request is rejected with `406 Not Acceptable`, and the widget and the landing page are left unchanged. The response carries only a `non_field_errors` message naming the referencing record — there is no `error_code`:

```json
{
  "non_field_errors": "Cannot delete some instances of model 'Widget' because they are referenced through protected foreign keys: 'DataSourceLandingPage.widget'.: {<DataSourceLandingPage: Acme Supplies>}"
}
```

To delete such a widget, first delete the data source landing page that uses it, then repeat the request.

### Dynamic Settings & Environment Variables

These endpoints are affected by the following dynamic setting, configured in the management panel. It is referenced again in the description of the operations it affects.

| Key                             | Type    | Default                                                    | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------- | ------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IGNORE_ACCEPT_LANGUAGE_HEADER` | boolean | `true` (falls back to the Django setting of the same name) | Whether the `Accept-Language` header is discarded before the request is processed. Affects **every** operation: the language it selects decides which localizable attribute values are returned, which ones a create or update writes and replaces, and the language business-error messages are translated into. While it is `true` (the default), the header is honored only when the request also carries an `X-Omnitron-Session` header; otherwise the deployment's default language is used. |

No other dynamic setting is read on the request path of these endpoints. The settings registered for the CMS area — e-mail, sitemap, database template prefixes, special pages, pretty-URL redirects, and push notifications — do not affect widgets.

**Deployment settings.** The following Django settings are part of the deployment configuration, supplied through environment variables of the same names, and cannot be changed at runtime:

| Setting         | Default             | Effect                                                                                                                                                                                                               |
| --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LANGUAGE_CODE` | `tr-tr`             | The default language. Its localizable attribute values are the fallback returned when the request language has no value of its own, and it is the language used when the request language is not otherwise resolved. |
| `LANGUAGES`     | deployment-specific | The languages a request can resolve to. Localizable attribute values can be stored for each of them.                                                                                                                 |


---

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