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.
Token credential sent in the Authorization header, in the form: Token <your-token>. Requires a staff (admin) account.
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).
The display name of the widget.
Summer PicksThe 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.
summer-picksThe path of the template that renders the widget.
widgets/product-carousel.htmlThe identifier of the widget type whose schema defines the accepted attributes.
3The identifier of the product collection whose products the widget shows.
12The maximum number of products the widget shows. Defaults to 10 on create; left out on full update, it keeps its current value.
10The 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.
first_itemThe created product collection widget.
A product collection widget — a CMS widget that renders products from a product collection.
The unique identifier of the widget.
When the widget was created.
When the widget was last modified.
The display name of the widget.
Summer PicksThe identifier storefront templates use to render the widget. Unique across all CMS widgets.
summer-picksThe identifier of the widget type whose schema defines the accepted attributes.
3The path of the template that renders the widget.
widgets/product-carousel.htmlThe identifier of the product collection whose products the widget shows.
12The maximum number of products the widget shows.
10The value of the extraction strategy, or null when the default strategy is used. See Extraction Strategies in the section introduction.
omnishop.search.strategies.FirstItemSearchExtractionStrategyPossible values: The request contains invalid or missing data.
Authentication credentials were not provided or are invalid.
The authenticated user does not have administrator privileges.
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).
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?

