Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

post
/product_collection_widgets/
Authorizations
AuthorizationstringRequired

Token credential sent in the Authorization header, in the form: Token <your-token>. Requires a staff (admin) account.

Body

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).

namestring · max: 255Required

The display name of the widget.

Example: Summer Picks
slugstring · max: 255Optional

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.

Example: summer-picks
templatestring · max: 512Required

The path of the template that renders the widget.

Example: widgets/product-carousel.html
widget_typeintegerRequired

The identifier of the widget type whose schema defines the accepted attributes.

Example: 3
product_collectionintegerRequired

The identifier of the product collection whose products the widget shows.

Example: 12
product_limitinteger · min: 1Optional

The maximum number of products the widget shows. Defaults to 10 on create; left out on full update, it keeps its current value.

Example: 10
extraction_strategystring · nullableOptional

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.

Example: first_item
Responses
201

The created product collection widget.

application/json

A product collection widget — a CMS widget that renders products from a product collection.

pkintegerRead-onlyOptional

The unique identifier of the widget.

created_datestring · date-timeRead-onlyOptional

When the widget was created.

modified_datestring · date-timeRead-onlyOptional

When the widget was last modified.

namestring · max: 255Optional

The display name of the widget.

Example: Summer Picks
slugstring · max: 255Optional

The identifier storefront templates use to render the widget. Unique across all CMS widgets.

Example: summer-picks
widget_typeintegerOptional

The identifier of the widget type whose schema defines the accepted attributes.

Example: 3
templatestring · max: 512Optional

The path of the template that renders the widget.

Example: widgets/product-carousel.html
product_collectionintegerOptional

The identifier of the product collection whose products the widget shows.

Example: 12
product_limitinteger · min: 1Optional

The maximum number of products the widget shows.

Example: 10
extraction_strategystring,null · enum · nullableOptional

The value of the extraction strategy, or null when the default strategy is used. See Extraction Strategies in the section introduction.

Example: omnishop.search.strategies.FirstItemSearchExtractionStrategyPossible values:
post/product_collection_widgets/
POST /api/v1/remote/1/product_collection_widgets/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 220

{
  "name": "Summer Picks",
  "slug": "summer-picks",
  "template": "widgets/product-carousel.html",
  "widget_type": 3,
  "attributes": {
    "title": "Summer Picks"
  },
  "product_collection": 12,
  "product_limit": 10,
  "extraction_strategy": "first_item"
}
{
  "pk": 1,
  "created_date": "2026-01-01T00:00:00.000Z",
  "modified_date": "2026-01-01T00:00:00.000Z",
  "attributes": {
    "title": "Summer Picks",
    "layout": "carousel"
  },
  "name": "Summer Picks",
  "slug": "summer-picks",
  "widget_type": 3,
  "template": "widgets/product-carousel.html",
  "attributes_kwargs": {
    "layout": {
      "value": "carousel",
      "data_type": "dropdown"
    }
  },
  "product_collection": 12,
  "product_limit": 10,
  "extraction_strategy": "omnishop.search.strategies.FirstItemSearchExtractionStrategy"
}

Last updated

Was this helpful?