Recommendation Widgets API
Overview
A recommendation widget is a named shelf that a storefront requests by its id from
POST /recommendations/widgets/{widget_id}. These
endpoints manage the widgets themselves: their configuration, their rules, and the rules for
individual seed products on seeded widgets.
Recommendation widgets must be enabled for your account. Until they are, every operation on this
page, reads included, returns 403 feature_not_enabled. Contact your Marqo account manager.
| Method | Path | Description |
|---|---|---|
GET | /widgets | List widgets |
POST | /widgets | Create a widget |
GET | /widgets/{widgetId} | Get a widget, with its rules |
PUT | /widgets/{widgetId} | Update a widget's configuration |
DELETE | /widgets/{widgetId} | Delete a widget and its seed rules |
GET | /widgets/{widgetId}/rules | Get a widget's rules |
PUT | /widgets/{widgetId}/rules | Replace a widget's rules |
GET | /widgets/{widgetId}/products | List a seeded widget's per-product rules |
GET | /widgets/{widgetId}/products/{productId} | Get one seed product's rules |
PUT | /widgets/{widgetId}/products/{productId} | Create or replace one seed product's rules |
DELETE | /widgets/{widgetId}/products/{productId} | Delete one seed product's rules |
Paths are relative to https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise.
Widget fields
| Field | Type | Description |
|---|---|---|
id | string | The id storefronts request the widget by. Letters, digits, _ and -, starting with a letter or digit, up to 64 characters. Case-sensitive. Set on create. |
label | string | The widget's name, up to 256 characters. |
source | string | Where candidates come from. See Sources. |
trigger | string | The query (search) or collection id (collection). Required for those sources and not allowed for others. Stored and returned exactly as sent. |
seedMatchFields | string[] | Seeded sources only. Up to 3 fields whose values candidates must share with the seed product. See Match seed fields. |
rules | object | The widget's rules. See Widget rules. Returned by GET /widgets/{widgetId}, not by the list. |
eligibleToServe | boolean | Read-only. Whether the saved configuration can serve: false for a hand-picked widget with no rules. It doesn't say whether the configuration is published yet. |
seedCount | integer | Read-only. Seeded widgets only: how many seed products have rules. |
revision | string | Read-only. Covers the configuration only; the rules have their own revision. |
createdAt | string | Read-only. |
updatedAt | string | Read-only. When the widget's rules were last saved, or when it was created if they never were. |
Sources
source | Console name | Candidates | Takes |
|---|---|---|---|
search | Search query | Results of a fixed query | trigger |
collection | Collection | Products of a collection | trigger |
custom | Hand-picked | Only the products the rules pin | |
for_you | For You | Personalised per shopper | |
similar | Similar products | Similar to the seed product | seedMatchFields |
complementary | Complementary products | Bought with the seed product | seedMatchFields |
complete_the_look | Complete the look | Completes a look with the seed product | seedMatchFields |
The last three are seeded: each storefront request names the seed product, and the widget can carry rules per seed product. New sources may be added; treat an unknown value as "other".
List widgets
Endpoint: GET /widgets
Returns a page of widget summaries (without rules), ordered by id, paginated with limit and
cursor (see Pagination).
curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets?limit=100" \
-H "Authorization: Bearer {api_key}"
{
"items": [
{
"id": "shop-the-colour",
"label": "Shop the colour",
"source": "similar",
"seedMatchFields": ["color"],
"eligibleToServe": true,
"seedCount": 12,
"revision": "e1c2a3b4d5f60718293a4b5c6d7e8f90",
"createdAt": "2026-09-14T22:08:17.512Z",
"updatedAt": "2026-10-02T04:11:52.003Z"
}
],
"nextCursor": null
}
Create a widget
Endpoint: POST /widgets
id, label and source are required. rules is optional and takes the
widget rules fields.
- cURL
- JavaScript
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"id": "summer-picks",
"label": "Summer picks",
"source": "custom",
"rules": {
"pins": [
{ "position": 1, "documentId": "sku-48213" },
{ "position": 2, "documentId": "sku-10377" }
]
}
}'
await fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets", {
method: "POST",
headers: {
Authorization: "Bearer {api_key}",
"Content-Type": "application/json",
},
body: JSON.stringify({
id: "summer-picks",
label: "Summer picks",
source: "custom",
rules: {
pins: [
{ position: 1, documentId: "sku-48213" },
{ position: 2, documentId: "sku-10377" },
],
},
}),
});
Returns 201 with the created widget.
- A hand-picked (
custom) widget is eligible to serve only once it has at least one rule, so sendruleshere or follow up with Replace widget rules. Every other source defines its own shelf and is eligible straight away. Either way, the widget serves once published. - If a widget with the id exists and equals the request, the request returns
200with it, so a retried create succeeds; otherwise409 already_exists. 409 widget_delete_pending: a widget with this id is still being deleted. Retry itsDELETE, or wait.If-MatchandIf-None-Matchare refused with400 validation_error.
Get a widget
Endpoint: GET /widgets/{widgetId}
curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets/summer-picks \
-H "Authorization: Bearer {api_key}"
Returns the widget including its rules, or 404 widget_not_found.
Update a widget's configuration
Endpoint: PUT /widgets/{widgetId}
Replaces label, source, trigger and seedMatchFields; label and source are required.
The widget's rules and seed rules are kept. This PUT never creates a widget: a missing widget is
404 widget_not_found. Takes an optional If-Match with the widget's revision.
curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets/new-arrivals \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"label": "New arrivals",
"source": "collection",
"trigger": "new-in"
}'
- Switching a seeded widget to an unseeded source fails with
409 widget_has_seedswhile it has seed product rules. Delete them first. - Changing to a source that ignores
overrideRelevance(collection,custom,complementary) stores it asfalseon the kept rules and their scheduled overrides. - Each
seedMatchFieldsentry must be a field that exists in the index. - The body accepts only the configuration fields, not the read-only fields a
GETreturns.
Delete a widget
Endpoint: DELETE /widgets/{widgetId}
curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets/summer-picks \
-H "Authorization: Bearer {api_key}"
Returns 204. The widget and all its seed product rules leave the saved configuration as one
step, and the widget stops serving once that is published.
If a widget with many seed rules can't be fully removed within the request, the response is
503 delete_incomplete with Retry-After. The widget is already gone from the saved configuration
and reads return 404; retry the DELETE to finish, which returns 204 whatever If-Match says.
Widget rules
A widget's rules apply only to that widget: the index's global rules never apply to a widget. The rules always exist while the widget does; a widget with none returns empty lists.
Widget rules take the same pins, exclusions, score modifiers, filters, recency and scheduled overrides as trigger rules, with these differences:
| Field | Widget rules |
|---|---|
inheritGlobalFilters, inheritGlobalScoreModifiers | Not accepted: global rules don't apply. |
reinforcementLearning | enable (default) or disable. |
overrideRelevance | Ignored, and stored as false, for collection, custom and complementary widgets. |
scheduledOverrides | At most 20. Ended overrides aren't archived; remove them to make room. |
Get widget rules
Endpoint: GET /widgets/{widgetId}/rules
{
"pins": [{ "position": 1, "documentId": "sku-48213" }],
"excludes": [],
"scoreModifiers": {},
"filters": ["in_stock:true"],
"recency": null,
"applyOutOfStockFilter": true,
"reinforcementLearning": "enable",
"overrideRelevance": false,
"scheduledOverrides": [],
"revision": "7f3e2d1c0b9a48576a5b4c3d2e1f0a9b",
"updatedAt": "2026-10-02T04:11:52.003Z"
}
Replace widget rules
Endpoint: PUT /widgets/{widgetId}/rules
curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets/new-arrivals/rules \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"pins": [{ "position": 1, "documentId": "sku-48213" }],
"filters": ["in_stock:true"],
"recency": { "before": 14, "after": 3, "weight": 2 }
}'
- A hand-picked (
custom) widget must keep at least one rule (422 widget_rules_required); delete the widget instead. Flags alone don't count as a rule. - On seeded widgets, the widget's exclusions plus any seed product's exclusions must stay within the per-rule-set exclusion limit.
- Takes
If-Matchonly. A missing widget is404 widget_not_found.
Seed product rules
A seeded widget (similar, complementary, complete_the_look) can carry rules for individual
seed products, layered over the widget's rules when a storefront request is seeded with that
product. See Product-level rules for
how they combine.
productId is the product's id, as the storefront sends it in seedParentProductIds (a Shopify
product id, for example), not a variant's document _id. It may contain letters, digits, _ and
-, up to 256 characters.
Seed rules take pins, exclusions, score modifiers, filters and recency, plus:
| Field | Default | Description |
|---|---|---|
inheritWidgetFilters | true | Also apply the widget's filters. |
inheritWidgetScoreModifiers | true | Also apply the widget's score modifiers and recency. |
List seed products
Endpoint: GET /widgets/{widgetId}/products
Returns a summary of every seed product with rules (at most 500, so not paginated):
{
"items": [
{
"productId": "8123456789012",
"pinCount": 1,
"excludeCount": 0,
"filterCount": 0,
"scoreModifierCount": 2,
"hasRecency": false,
"revision": "2c4e6a8b0d1f43658799aabbccddeeff",
"updatedAt": "2026-10-05T01:22:09.441Z"
}
]
}
Get, replace or delete a seed product's rules
Endpoints: GET, PUT and DELETE /widgets/{widgetId}/products/{productId}
curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/widgets/shop-the-colour/products/8123456789012 \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"pins": [{ "position": 1, "documentId": "sku-hero-black" }],
"excludes": [{ "documentId": "sku-discontinued" }]
}'
- Only seeded widgets take seed rules (
400 widget_not_seededotherwise). - A seed with no rules is
422 seed_rules_required, even if it sets flags; delete it instead. A score modifier counts as a rule at any weight, so{"scoreModifiers": {"price": 0}, "inheritWidgetScoreModifiers": false}drops the widget's boosts for this product. - A widget takes at most 500 seed products with rules (
422 limit_max_seeds_per_widget). PUTtakesIf-MatchorIf-None-Match: *. A missing widget is404 widget_not_foundwhatever the preconditions say.GETandDELETEof a product without rules return404 seed_not_found.