> 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/product-collection-widgets/create-a-product-collection-widget.md).

# Create a product collection widget

Creates a product collection widget.

`name`, `template`, `widget_type`, `product_collection` and `attributes` are required (send `{}` for `attributes` when there are no values). When `slug` is not sent it is generated from `name`; see **Slug Handling** in the section introduction for the conflicts that can occur.

Localizable attributes are written in the language active for the request — see `IGNORE_ACCEPT_LANGUAGE_HEADER` in the section introduction.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Product Collection Widgets","description":"Administrative endpoints for **product collection widgets** — CMS widgets that render a list of products from a product collection on the storefront. A product collection widget combines the fields of a regular CMS widget (name, slug, template, widget type, and attributes defined by the widget type's schema) with a product collection, the maximum number of products to show, and the strategy used to pick which variant represents each product.\n\nStorefront templates render a widget by its `slug`. When rendered, the widget searches the products of its collection, applies the collection's sort option, takes at most `product_limit` products, and passes them to the template together with the widget's attributes.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* Retrieve a paginated list of product collection widgets.\n* Filter by name, slug, template, widget type, product collection, product limit, extraction strategy, or creation or modification date.\n* Order results with the `sort` parameter.\n\n**2. Widget Lifecycle Management**\n* Create a widget; the slug is generated from the name when it is not sent.\n* Retrieve, fully or partially update, or permanently delete a widget.\n\n**3. Detailed Representation**\n* `GET /product_collection_widgets/detailed/` and `GET /product_collection_widgets/{id}/detailed/` return the same records with the product collection expanded into a nested object instead of its identifier.\n\n## Product Collection Widget Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `pk` | integer | The unique identifier of the widget. Read-only. |\n| `name` | string (max 255) | The display name of the widget. Required on create and full update. |\n| `slug` | string (max 255) | The identifier storefront templates use to render the widget. Optional; when it is not sent on create, it is generated from `name`. Unique across **all** CMS widgets, not only product collection widgets. |\n| `template` | string (max 512) | The path of the template that renders the widget. Required on create and full update. |\n| `widget_type` | integer | The identifier of the widget type whose schema defines the accepted `attributes`. Required on create and on every update, including partial updates. |\n| `attributes` | object | The attribute values of the widget, keyed by the entries of the widget type's schema. Required on create and on every update, including partial updates (see **Attributes**). |\n| `attributes_kwargs` | object | Read-only supplementary detail the server derives for the stored attributes — for example the value and data type of a dropdown entry; plain text entries have no supplementary detail. It is returned in responses and ignored if sent. The detailed representation returns it in its stored form, which may carry additional internal keys such as `_translations`. |\n| `product_collection` | integer | The identifier of the product collection whose products the widget shows. Required on create and full update. Expanded into a nested object in the detailed representation. |\n| `product_limit` | integer | The maximum number of products the widget shows. Must be at least `1`. Defaults to `10`. |\n| `extraction_strategy` | string or `null` | Which variant represents each product in the widget (see **Extraction Strategies**). Defaults to `null`. |\n| `created_date` | string (date-time) | Read-only. When the widget was created. |\n| `modified_date` | string (date-time) | Read-only. When the widget was last modified. |\n\n## Attributes\n\nThe keys accepted in `attributes` come from the `schema` of the widget's widget type (managed through the `widget_types` endpoints).\n\n* `attributes` is required on create, full update and partial update — send an empty object (`{}`) if there are no values to set.\n* Every key must exist in the widget type's schema. An unknown key is rejected with `400`.\n* Each value is validated against its schema entry — for example a dropdown value must be one of the entry's choices, and a multi-value entry must be sent as a list. A value that does not satisfy its entry is rejected with `406` and the `attribute_input_type_100` code.\n* Required flags in the schema are **not** enforced — an empty object is accepted even when the schema marks entries as required.\n* Entries that the schema marks as localizable are stored per language: they are written to, and returned in, the language active for the request, falling back to the default language where a translation is missing.\n* The stored attributes are **replaced**, not merged — the object sent replaces the non-localizable attributes and the localizable attributes of the request's language. Localizable values stored for other languages are kept. See `IGNORE_ACCEPT_LANGUAGE_HEADER` under **Dynamic Settings & Environment Variables**.\n\n## Extraction Strategies\n\n`extraction_strategy` is accepted either by its **name** or by its **value**, and is always returned by its **value**. `null` means the default strategy is used.\n\n| Name | Value | Label |\n|------|-------|---------|\n| `default` | `omnishop.search.strategies.DefaultProductExtractionStrategy` | Default. |\n| `first_item` | `omnishop.search.strategies.FirstItemSearchExtractionStrategy` | First Variant. |\n| `listable_first` | `omnishop.search.strategies.ListableFirstProductExtractionStrategy` | Listable Variant First. |\n| `min_price_first` | `omnishop.search.strategies.MinPriceFirstProductExtractionStrategy` | Min Price Variant First. |\n| `max_price_first` | `omnishop.search.strategies.MaxPriceFirstProductExtractionStrategy` | Max Price Variant First. |\n| `all_sub_products` | `omnishop.search.strategies.AllSubProductsExtractionStrategy` | All Sub Products. |\n| `offer_product` | `omnishop.search.strategies.OfferProductExtractionStrategy` | Offer Product. |\n| `product_sorting_item` | `omnishop.search.strategies.ProductSortingItemExtractionStrategy` | Product Sorting Item. |\n\n## Slug Handling\n\n* When `slug` is sent and another CMS widget (of any kind) already uses it, the request is rejected with `400` on the `slug` field.\n* When `slug` is not sent on create, it is generated from `name` (for example `Summer Picks` → `summer-picks`). If the generated slug already belongs to another product collection widget, the request is rejected with `406` and the `cms_product_collection_widget_100` code. The generated slug must also not belong to a regular CMS widget — send an explicit, unused `slug` in that case.\n* On update, leaving `slug` out keeps the current slug; it is never regenerated from a new `name`.\n\n## Partial Updates\n\n> **Important:** a partial update (`PATCH`) requires both `widget_type` and `attributes` — the attribute keys are always validated against the widget type sent in the same request. Send the current values when they are not meant to change.\n\n## Deleting a Widget\n\n`DELETE /product_collection_widgets/{id}/` is a **hard delete** — the widget is permanently removed. A widget still used by a data source landing page is protected and cannot be deleted; the request is rejected with `406`. Detach it from the landing page first.\n\n## Filtering & Ordering\n\n| Parameter | Match |\n|-----------|-------|\n| `name` | Case-insensitive partial match on the name. |\n| `slug` | Case-insensitive partial match on the slug. |\n| `slug__in` | A comma-separated list of slugs — keeps the widgets whose slug is exactly one of them. |\n| `template` | Case-insensitive partial match on the template path. |\n| `widget_type` | The identifier of a widget type. An identifier that does not exist is rejected with `400`. |\n| `product_collection` | The identifier of a product collection. An identifier that does not exist is rejected with `400`. |\n| `product_limit` | Exact match on the product limit. |\n| `extraction_strategy` | Case-insensitive partial match on the stored strategy **value** (for example `FirstItem`); strategy names such as `first_item` do not match. Send `NULL_VALUE` to return only widgets without a strategy, or `NOT_NULL_VALUE` to return only widgets that have one. |\n| `created_date`, `modified_date` | Exact match on a full ISO 8601 date-time. A date without a time is rejected with `400`. |\n\nNo default ordering is applied; use the `sort` parameter to order the results by any field, prefixing it with a hyphen for descending order.\n\n## Storefront Caching\n\nWhen storefront templates render a widget by its slug, the rendered content is cached for a short time, so a change made through these endpoints may not appear on the storefront immediately.\n\n## Error Codes\n\nRequests that are well-formed but conflict with a business rule are answered with `406 Not Acceptable` and carry one of the following codes.\n\n| Code | Meaning |\n|------|---------|\n| `cms_product_collection_widget_100` | The slug generated from `name` already belongs to another product collection widget. |\n| `attribute_input_type_100` | An attribute value does not satisfy its schema entry (for example a dropdown value outside its choices, or a single value sent for a multi-value entry). |\n\nA delete rejected because the widget is still used by a data source landing page is also answered with `406`; that response carries only `non_field_errors`, without an `error_code`.\n\n## Dynamic Settings & Environment Variables\n\nNo dynamic setting changes the request or response schema of these endpoints, but the two below affect their behavior. Each is referenced again in the description of the operations it affects.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `IGNORE_ACCEPT_LANGUAGE_HEADER` | boolean | `true` | Whether the `Accept-Language` header is discarded before the request is processed. Affects **create**, **update** and **partial update** (the language localizable attributes are written to) and every read operation (the language localizable attributes are returned in). While it is `true` (the default), the header is honored only when the request also carries an `X-Omnitron-Session` header; otherwise it is removed and a plain API request falls back to the server's default language (`LANGUAGE_CODE`). For example, a create sent with `Accept-Language: en-us` but without `X-Omnitron-Session` stores its localizable values under the default language, not under `en-us`. |\n| `IGNORE_DELETED_ITEMS_SIGNAL` | array of strings | `[\"django_audit_events.AuditEvent\", \"django_audit_events.ArchivedAuditEvent\", \"sessions.Session\", \"datawarehouse.DeletedItem\"]` | The model labels excluded from delete tracking. Affects **delete**: unless `cms.ProductCollectionWidget` and `cms.Widget` are added to this list, deleting a widget also records two deleted-item entries (one per model, because a product collection widget is stored as a widget plus its product collection extension), which are exposed through the data-warehouse `deleted-items` endpoint. Listing only one of the two labels suppresses only that model's entry. The API response is identical either way. |\n\n**Environment variables and server settings**\n\n| Setting | Default | Effect |\n|---------|---------|--------|\n| `LANGUAGE_CODE` | `tr-tr` | The server's default language. Localizable attributes are written to and returned in this language whenever the request language is not resolved to something else — see `IGNORE_ACCEPT_LANGUAGE_HEADER` above. |"}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"ProductCollectionWidgetRequest":{"type":"object","description":"Request body for creating a product collection widget or fully updating an existing one. `name`, `template`, `widget_type`, `product_collection` and `attributes` are required (send `{}` for `attributes` when there are no values).","properties":{"name":{"type":"string","maxLength":255,"description":"The display name of the widget."},"slug":{"type":"string","maxLength":255,"description":"The identifier storefront templates use to render the widget. Must not already belong to another CMS widget. When it is left out on create, it is generated from `name`; on update, leaving it out keeps the current slug."},"template":{"type":"string","maxLength":512,"description":"The path of the template that renders the widget."},"widget_type":{"type":"integer","description":"The identifier of the widget type whose schema defines the accepted attributes."},"attributes":{"type":"object","description":"The attribute values of the widget. Every key must exist in the widget type's schema, and each value must satisfy its schema entry. The object sent replaces the stored attributes entirely.","additionalProperties":true},"product_collection":{"type":"integer","description":"The identifier of the product collection whose products the widget shows."},"product_limit":{"type":"integer","minimum":1,"description":"The maximum number of products the widget shows. Defaults to `10` on create; left out on full update, it keeps its current value."},"extraction_strategy":{"type":["string","null"],"description":"The extraction strategy, given by its **name** (for example `first_item`) or its **value**. `null` or leaving it out means the default strategy is used — on full update, leaving it out resets it to `null`."}},"required":["name","template","widget_type","product_collection","attributes"]},"ProductCollectionWidget":{"type":"object","description":"A product collection widget — a CMS widget that renders products from a product collection.","properties":{"pk":{"type":"integer","description":"The unique identifier of the widget.","readOnly":true},"created_date":{"type":"string","format":"date-time","description":"When the widget was created.","readOnly":true},"modified_date":{"type":"string","format":"date-time","description":"When the widget was last modified.","readOnly":true},"attributes":{"type":"object","description":"The attribute values of the widget, keyed by the entries of the widget type's schema. Localizable entries are returned in the language active for the request.","additionalProperties":true},"name":{"type":"string","maxLength":255,"description":"The display name of the widget."},"slug":{"type":"string","maxLength":255,"description":"The identifier storefront templates use to render the widget. Unique across all CMS widgets."},"widget_type":{"type":"integer","description":"The identifier of the widget type whose schema defines the accepted attributes."},"template":{"type":"string","maxLength":512,"description":"The path of the template that renders the widget."},"attributes_kwargs":{"type":"object","description":"Supplementary detail the server derives for the stored attributes — for example the value and data type of a dropdown entry; plain text entries have no supplementary detail. Read-only: it is returned in responses and ignored if sent.","additionalProperties":true,"readOnly":true},"product_collection":{"type":"integer","description":"The identifier of the product collection whose products the widget shows."},"product_limit":{"type":"integer","minimum":1,"description":"The maximum number of products the widget shows."},"extraction_strategy":{"type":["string","null"],"description":"The **value** of the extraction strategy, or `null` when the default strategy is used. See **Extraction Strategies** in the section introduction.","enum":["omnishop.search.strategies.DefaultProductExtractionStrategy","omnishop.search.strategies.FirstItemSearchExtractionStrategy","omnishop.search.strategies.ListableFirstProductExtractionStrategy","omnishop.search.strategies.MinPriceFirstProductExtractionStrategy","omnishop.search.strategies.MaxPriceFirstProductExtractionStrategy","omnishop.search.strategies.AllSubProductsExtractionStrategy","omnishop.search.strategies.OfferProductExtractionStrategy","omnishop.search.strategies.ProductSortingItemExtractionStrategy",null]}}},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true},"ProductCollectionWidgetBusinessError":{"type":"object","description":"Returned when a request is valid in form but violates a business rule of the product collection widgets. The codes these endpoints raise are listed under **Error Codes** in the section introduction.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the business rule that was violated."},"error_code":{"type":"string","description":"A stable code identifying the specific business rule violation."}},"additionalProperties":true}},"responses":{"ValidationError":{"description":"The request contains invalid or missing data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ProductCollectionWidgetBusinessError":{"description":"The request is well-formed but violates a business rule — an attribute value does not satisfy its schema entry (`attribute_input_type_100`), or, on create only, the slug generated from `name` already belongs to another product collection widget (`cms_product_collection_widget_100`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCollectionWidgetBusinessError"}}}}}},"paths":{"/product_collection_widgets/":{"post":{"tags":["Product Collection Widgets"],"operationId":"createProductCollectionWidget","summary":"Create a product collection widget","description":"Creates a product collection widget.\n\n`name`, `template`, `widget_type`, `product_collection` and `attributes` are required (send `{}` for `attributes` when there are no values). When `slug` is not sent it is generated from `name`; see **Slug Handling** in the section introduction for the conflicts that can occur.\n\nLocalizable attributes are written in the language active for the request — see `IGNORE_ACCEPT_LANGUAGE_HEADER` in the section introduction.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCollectionWidgetRequest"}}}},"responses":{"201":{"description":"The created product collection widget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCollectionWidget"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"406":{"$ref":"#/components/responses/ProductCollectionWidgetBusinessError"}}}}}}
```


---

# 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/product-collection-widgets/create-a-product-collection-widget.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.
