Merchandising API
Overview
The Merchandising API gives you programmatic access to the merchandising you would otherwise manage in the Marqo console. Use it to script rule changes, sync rules from another system, run campaigns from your own tooling, or let an agent manage merchandising for you.
Everything the API writes is the same data the console edits. A rule saved through the API shows up in the console, and a console edit shows up in the API.
| Resource | What it controls | Page |
|---|---|---|
| Global rules | Default filters, boosts, recency and reinforcement learning for every query, collection or recommendation in a context | Global Rules |
| Trigger rules | Pins, exclusions, boosts, filters, recency and scheduled overrides for one search query, collection or seed product | Trigger Rules |
| Synonyms | One-way rewrites of a child phrase to its parent phrase | Synonyms |
| Redirects | Sending a search for a term straight to a URL | Redirects |
| Recommendation widgets | Named recommendation shelves, their rules and per-product seed rules | Recommendation Widgets |
All endpoints live under:
https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise
{index_name} is the index name or an alias of it. The API serves ecommerce indexes only.
The API does not cover A/B tests, merchandising profiles, facet rules or merchandising settings such as the recency field. Manage those in the console. Rules that the console writes for a merchandising profile keep serving and are not visible through the API (see Merchandising profiles).
Authentication
Send your API key as a bearer token:
Authorization: Bearer {api_key}
Keep the key server-side.
| Operation | Minimum key scope |
|---|---|
GET (any read) | Read |
PUT, POST, PATCH, DELETE | Read + Write |
A key whose scope is too narrow gets 403 insufficient_scope. Keys created before scopes existed
are treated as Admin. Recommendation widgets must also be enabled for your account: every
/widgets operation, reads included, returns 403 feature_not_enabled until they are.
- cURL
- JavaScript
curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/running%20shoes \
-H "Authorization: Bearer {api_key}"
const trigger = encodeURIComponent("running shoes");
const response = await fetch(
`https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/${trigger}`,
{ headers: { Authorization: "Bearer {api_key}" } },
);
const rules = await response.json();
const revision = response.headers.get("ETag");
Contexts
Rules belong to a context, which says where they apply:
| Context | Applies to | Trigger is |
|---|---|---|
search | Search requests | The search query |
collection | Collection pages | The collection id |
similar | Similar recommendations | The seed product's document _id |
complementary | Complementary recommendations | The seed product's document _id |
complete_the_look | Complete the Look recommendations | The seed product's document _id |
Recommendation widgets have their own rules and are not addressed by context (see Recommendation Widgets).
Triggers in the path
A trigger, synonym phrase or redirect term is a single URL-encoded path segment. Encode it with
encodeURIComponent or your language's equivalent, so a / in it is sent as %2F and a % as
%25:
| Value | Path segment |
|---|---|
running shoes | running%20shoes |
50% off/sale | 50%25%20off%2Fsale |
shirts w/sleeves | shirts%20w%2Fsleeves |
Triggers are case-insensitive and stored in a canonical form: leading and trailing whitespace
removed, lower-cased and Unicode-normalised (NFC). /triggers/Summer-Sale and
/triggers/summer-sale address the same rule set, and responses return
"trigger": "summer-sale".
A few values can't be addressed and are refused with 400 validation_error:
- A value that is blank once its edge whitespace is removed.
- A value with a
.or..part between slashes (a/../b), or an empty part (a//b,/sale). A.inside a word is fine:v1.2and...are valid triggers. - A trigger that ends in
/(it would collide with the/schedule-historypath). Synonym parents and redirect terms may end in/. - A trigger longer than 256 characters, or longer than 960 bytes as UTF-8. Synonym phrases and redirect terms are at most 200 characters.
- Bytes that aren't valid UTF-8, a NUL (
%00) or a malformed escape such as%ZZ. The last two are refused at the edge with an HTML400page rather than a JSON error.
Read, edit, write back
Writes replace the whole resource. To change one rule, read the resource, edit it and send the whole body back. Request bodies accept the read-only fields of the matching response, so you can send back exactly what you read:
- Bookkeeping fields (
revision,updatedAt,selected,requestedTrigger) are ignored. - Identity fields (
context,trigger,productId, a redirect'sterm) must match the resource you are writing to, or the write fails with400 validation_error. This stops a body read from one trigger being written over another by mistake. - Any other unknown field is rejected with
400 validation_error.
Writing back an unchanged body stores nothing and keeps the revision.
Field types are strict: an integer field takes a JSON integer (1.0 and "3" are refused), and
strings are never coerced to numbers or booleans.
Revisions and concurrent edits
Every resource has a revision, returned in the body and as the ETag response header. A
revision is a hash of the resource's content, so it changes whenever the content changes
(including through the console) and comes back to the same value after an exact undo.
Preconditions are optional:
| Header | Effect |
|---|---|
If-Match: "{revision}" | Write only if the resource is still at that revision. Otherwise 412 revision_mismatch and nothing changes. |
If-None-Match: * | On a PUT that can create, create only if the resource doesn't exist yet. Otherwise 412 revision_mismatch. |
| Neither | The write is unconditional. The last write wins, even over an edit made in the console. |
curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/running%20shoes \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-H 'If-Match: "9c41e07b2d5a4f3e8a1b6c7d0e2f4a5b"' \
-d '{"pins": [{"position": 1, "documentId": "sku-48213"}]}'
Notes:
If-Matchtakes one quoted revision. The weak formW/"…"is accepted, because compression at the edge can weaken anETag.*, lists and""are400 validation_error.- Sending both headers is
400 conflicting_preconditions. - Only a
PUTthat can create (trigger rules, a redirect, a seed product's rules) takesIf-None-Match. Any other write, including everyDELETE, refuses it with400 validation_error. - An empty
If-MatchorIf-None-Matchheader is dropped before it reaches the API, so the write goes through unconditionally. If you don't have a revision, leave the header out deliberately. GETignoresIf-None-Matchand always returns200with the body, never304.- Writes to something under a parent that doesn't exist (a deleted widget's rules or seeds, a
deleted synonym group's children) fail with the parent's
404, whatever the preconditions say.
Use preconditions when anything else (the console, another script, an agent) edits the same resources.
Pagination
Lists that can grow large are paginated with limit and cursor:
| Parameter | Description |
|---|---|
limit | Most items per page. Defaults to 20, at most 100 (synonyms: 10 and 25). Plain decimal digits only (01, +1 and 1.0 are refused). |
cursor | The nextCursor from the previous page. Opaque and tied to the endpoint it came from; a garbled or foreign cursor is 400 invalid_cursor. |
A response holds items and nextCursor, which is null on the last page. Pages aren't a
snapshot: paging while others edit never repeats an item, but can miss one created behind the
cursor. Redirects and a widget's seed products are bounded (500 each) and return in full.
When changes go live
A write goes through three stages:
- Saved. The write returned
2xx. It is durable and every read returns it. - Published. Rules are exported to the edge every five minutes, so a saved change is normally published within five minutes.
- Propagated. Edge caches then converge, typically within about 12 minutes plus the index's search response-cache TTL. This is an expected window, not a guarantee.
Redirects skip the export: search reads them directly, and edges cache an index's redirects for up to 10 minutes.
The API has no endpoint that reports whether a change is live. Atomicity covers the saved configuration: a change that spans several resources, such as deleting a widget with many seed rules, is saved as one step, but live traffic may briefly see part of it while it propagates.
Limits
| Limit | Default | Error |
|---|---|---|
| Trigger rule sets per index (including widget seed rules and console profile rule sets) | 1000 | 422 limit_max_triggers |
| Pins per rule set | 120 | 422 limit_max_pins_per_trigger |
| Highest pin position | 120 | 422 limit_max_pin_position |
| Exclusions per rule set | 5 | 422 limit_max_excludes_per_trigger |
| Pins, exclusions, boosts and filters combined, per rule set | 125 | 422 limit_max_rules_per_trigger |
| Filters per rule set | 10 | 400 validation_error |
| Scheduled overrides per rule set | 20 | 422 limit_max_scheduled_overrides_per_trigger |
| Seed products with rules per widget | 500 | 422 limit_max_seeds_per_widget |
| Redirects per index | 500 | 422 limit_max_redirects_per_index |
| Request body | 1 MiB | 400 resource_too_large |
Limits are set by Marqo. Filters, scheduled overrides, seed products and redirects are fixed; the
others can differ per index, and Marqo can raise them on request. No operation returns them; the
422 message names the list that overflowed and the index's limit.
Errors
Every error the API returns has this shape:
{
"detail": {
"code": "revision_mismatch",
"message": "The resource has changed since revision \"3f9a1c\". Read it again and retry."
}
}
Branch on code; the message is for people and its wording can change. New codes can be added,
so handle an unknown code by its HTTP status.
| Status | Codes | Meaning |
|---|---|---|
400 | validation_error | The body, a path parameter or a query parameter is invalid. The message names the field. |
400 | invalid_schedule_window, widget_not_seeded, conflicting_preconditions, resource_too_large, invalid_cursor | See the relevant section. |
401 | invalid_api_key | The API key is missing, unknown or revoked. |
403 | insufficient_scope, feature_not_enabled | See Authentication. |
404 | index_not_found, rule_set_not_found, synonym_group_not_found, redirect_not_found, widget_not_found, seed_not_found | The index or the resource doesn't exist for your account. |
409 | trigger_is_synonym_child, child_has_rules, phrase_in_use, ambiguous_synonym_group | A synonym protection. See Synonyms. |
409 | profile_rule_sets_exist, widget_delete_pending, widget_has_seeds, already_exists, merchandising_not_configured | The write conflicts with existing state. |
409 | concurrent_modification | Other writes to the index kept changing it while the request ran. Writes, and reads that combine several rows (lists, a widget, trigger rules), can return it. Retry after Retry-After. |
412 | revision_mismatch | A precondition failed. Nothing was written. |
422 | limit_* | A limit would be exceeded. |
422 | widget_rules_required, seed_rules_required | The write would leave a hand-picked widget or a seed with no rules. |
500 | widget_unreadable | A stored widget can't be read. Nothing was written; contact Marqo support. |
502 | upstream_error | The API couldn't complete the request. The outcome is unknown. |
503 | outcome_unknown | The request timed out. The outcome is unknown. |
503 | delete_incomplete | A widget delete stopped partway. Retry the DELETE after Retry-After. |
409 merchandising_not_configured means merchandising hasn't been set up on the index, so rule
and widget writes are refused (reads return empty or default resources, and synonym and redirect
writes still work). Contact Marqo support to set it up.
Retrying
- Retry
409 concurrent_modificationand503 delete_incompleteunchanged, after theRetry-Afterinterval. - After a timeout,
502 upstream_erroror503 outcome_unknown, the write may or may not have been applied. Sending it again applies it to the current state, so an unconditionalPUTcan overwrite someone else's change made in between. SendIf-Match(orIf-None-Match: *for a create) when others edit the same resources. A conditional retry may get412or404because its first attempt landed;GETthe resource and compare. - A retried create that already landed returns
200with the stored resource instead of409 already_exists. - A retried
DELETEwhose first attempt landed returns the resource's own404(rule_set_not_found,widget_not_foundand so on): treat that as done.index_not_foundis not; it means the index itself is gone. - Any other
4xxneeds the request or the state to change first.