Skip to main content

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.

note

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.

MethodPathDescription
GET/widgetsList widgets
POST/widgetsCreate 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}/rulesGet a widget's rules
PUT/widgets/{widgetId}/rulesReplace a widget's rules
GET/widgets/{widgetId}/productsList 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​

FieldTypeDescription
idstringThe id storefronts request the widget by. Letters, digits, _ and -, starting with a letter or digit, up to 64 characters. Case-sensitive. Set on create.
labelstringThe widget's name, up to 256 characters.
sourcestringWhere candidates come from. See Sources.
triggerstringThe query (search) or collection id (collection). Required for those sources and not allowed for others. Stored and returned exactly as sent.
seedMatchFieldsstring[]Seeded sources only. Up to 3 fields whose values candidates must share with the seed product. See Match seed fields.
rulesobjectThe widget's rules. See Widget rules. Returned by GET /widgets/{widgetId}, not by the list.
eligibleToServebooleanRead-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.
seedCountintegerRead-only. Seeded widgets only: how many seed products have rules.
revisionstringRead-only. Covers the configuration only; the rules have their own revision.
createdAtstringRead-only.
updatedAtstringRead-only. When the widget's rules were last saved, or when it was created if they never were.

Sources​

sourceConsole nameCandidatesTakes
searchSearch queryResults of a fixed querytrigger
collectionCollectionProducts of a collectiontrigger
customHand-pickedOnly the products the rules pin
for_youFor YouPersonalised per shopper
similarSimilar productsSimilar to the seed productseedMatchFields
complementaryComplementary productsBought with the seed productseedMatchFields
complete_the_lookComplete the lookCompletes a look with the seed productseedMatchFields

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 -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" }
]
}
}'

Returns 201 with the created widget.

  • A hand-picked (custom) widget is eligible to serve only once it has at least one rule, so send rules here 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 200 with it, so a retried create succeeds; otherwise 409 already_exists.
  • 409 widget_delete_pending: a widget with this id is still being deleted. Retry its DELETE, or wait.
  • If-Match and If-None-Match are refused with 400 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_seeds while it has seed product rules. Delete them first.
  • Changing to a source that ignores overrideRelevance (collection, custom, complementary) stores it as false on the kept rules and their scheduled overrides.
  • Each seedMatchFields entry must be a field that exists in the index.
  • The body accepts only the configuration fields, not the read-only fields a GET returns.

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:

FieldWidget rules
inheritGlobalFilters, inheritGlobalScoreModifiersNot accepted: global rules don't apply.
reinforcementLearningenable (default) or disable.
overrideRelevanceIgnored, and stored as false, for collection, custom and complementary widgets.
scheduledOverridesAt 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-Match only. A missing widget is 404 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:

FieldDefaultDescription
inheritWidgetFilterstrueAlso apply the widget's filters.
inheritWidgetScoreModifierstrueAlso 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_seeded otherwise).
  • 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).
  • PUT takes If-Match or If-None-Match: *. A missing widget is 404 widget_not_found whatever the preconditions say.
  • GET and DELETE of a product without rules return 404 seed_not_found.