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

# List product collection widgets

Returns a paginated list of product collection widgets. `product_collection` is returned as an identifier; use `GET /product_collection_widgets/detailed/` to receive it as a nested object.

Localizable attributes are returned 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."}},"parameters":{"page":{"name":"page","in":"query","required":false,"description":"The page number to return.","schema":{"type":"integer","default":1}},"limit":{"name":"limit","in":"query","required":false,"description":"The number of items to return per page.","schema":{"type":"integer","default":10}},"sort":{"name":"sort","in":"query","required":false,"description":"Orders the results by one or more fields. Separate multiple fields with commas. Prefix a field with a hyphen (`-`) for descending order.","schema":{"type":"string"}},"productCollectionWidgetNameFilter":{"name":"name","in":"query","required":false,"description":"Filter by name. Case-insensitive partial match.","schema":{"type":"string"}},"productCollectionWidgetSlugFilter":{"name":"slug","in":"query","required":false,"description":"Filter by slug. Case-insensitive partial match.","schema":{"type":"string"}},"productCollectionWidgetSlugInFilter":{"name":"slug__in","in":"query","required":false,"description":"A comma-separated list of slugs. Keeps the widgets whose slug is exactly one of them.","schema":{"type":"string"}},"productCollectionWidgetTemplateFilter":{"name":"template","in":"query","required":false,"description":"Filter by template path. Case-insensitive partial match.","schema":{"type":"string"}},"productCollectionWidgetWidgetTypeFilter":{"name":"widget_type","in":"query","required":false,"description":"Filter by widget type identifier. An identifier that does not exist is rejected with `400`.","schema":{"type":"integer"}},"productCollectionWidgetProductCollectionFilter":{"name":"product_collection","in":"query","required":false,"description":"Filter by product collection identifier. An identifier that does not exist is rejected with `400`.","schema":{"type":"integer"}},"productCollectionWidgetProductLimitFilter":{"name":"product_limit","in":"query","required":false,"description":"Filter by exact product limit.","schema":{"type":"integer"}},"productCollectionWidgetExtractionStrategyFilter":{"name":"extraction_strategy","in":"query","required":false,"description":"Filter by 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.","schema":{"type":"string"}},"productCollectionWidgetCreatedDateFilter":{"name":"created_date","in":"query","required":false,"description":"Filter by exact creation date-time (ISO 8601). A date without a time is rejected with `400`.","schema":{"type":"string","format":"date-time"}},"productCollectionWidgetModifiedDateFilter":{"name":"modified_date","in":"query","required":false,"description":"Filter by exact modification date-time (ISO 8601). A date without a time is rejected with `400`.","schema":{"type":"string","format":"date-time"}}},"schemas":{"PaginatedProductCollectionWidgetList":{"type":"object","description":"A paginated list of product collection widgets.","properties":{"count":{"type":"integer","description":"Total number of widgets matching the request."},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page, or `null` if this is the last page."},"previous":{"type":["string","null"],"format":"uri","description":"URL of the previous page, or `null` if this is the first page."},"results":{"type":"array","description":"The widgets on the current page.","items":{"$ref":"#/components/schemas/ProductCollectionWidget"}}}},"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}},"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"}}}},"InvalidPage":{"description":"The requested `page` does not exist — it is past the last page or not a valid page number. Paginated list endpoints answer with `404` rather than an empty page. The literal value `last` is accepted and returns the final page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/product_collection_widgets/":{"get":{"tags":["Product Collection Widgets"],"operationId":"listProductCollectionWidgets","summary":"List product collection widgets","description":"Returns a paginated list of product collection widgets. `product_collection` is returned as an identifier; use `GET /product_collection_widgets/detailed/` to receive it as a nested object.\n\nLocalizable attributes are returned in the language active for the request — see `IGNORE_ACCEPT_LANGUAGE_HEADER` in the section introduction.","parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/productCollectionWidgetNameFilter"},{"$ref":"#/components/parameters/productCollectionWidgetSlugFilter"},{"$ref":"#/components/parameters/productCollectionWidgetSlugInFilter"},{"$ref":"#/components/parameters/productCollectionWidgetTemplateFilter"},{"$ref":"#/components/parameters/productCollectionWidgetWidgetTypeFilter"},{"$ref":"#/components/parameters/productCollectionWidgetProductCollectionFilter"},{"$ref":"#/components/parameters/productCollectionWidgetProductLimitFilter"},{"$ref":"#/components/parameters/productCollectionWidgetExtractionStrategyFilter"},{"$ref":"#/components/parameters/productCollectionWidgetCreatedDateFilter"},{"$ref":"#/components/parameters/productCollectionWidgetModifiedDateFilter"}],"responses":{"200":{"description":"A page of product collection widgets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedProductCollectionWidgetList"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/InvalidPage"}}}}}}
```


---

# 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/list-product-collection-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.
