Seekmodo

Seekmodo developer docs

Reference for the REST shim, MCP JSON-RPC surface, and storefront connectors. Authenticate with HMAC; replay window is 5 minutes.

Merchandising

Search relevance is self-tuning, but every store has business rules a model can't learn from clicks alone: the new collection that must appear first this week, the SKU your warehouse can't fulfil right now, the seasonal promotion. The Merchandising surface at admin.seekmodo.com → Merchandising is where you express those rules.

Five primitives

Every override falls into one of these buckets. The Merchandising landing page tabs across them; the per-tab forms share the same query / region / lifetime fields.

  • Pins — “for this query, this document must appear at this position.”
  • Boosts & deboosts — “for this query (or all queries), nudge documents matching this filter up or down by this percentage.”
  • Suppressions — “hide documents matching this filter, period.”
  • A/B experiments — run two variants of any of the above against a random shopper split; promote the winner.
  • Category merchandising — drag-and-drop order for the products inside a category. Covered in its own runbook.

Pins

The bluntest tool. A pin says “this product appears in slot N for this query, no matter what the ranker thinks.” Use pins for editorial moments (homepage hero of the week, Black Friday hero), for bridging while the ranker learns a new product (pin to #1 for the first 48 hours of a launch), or for legal/contractual obligations.

Anatomy of a pin row:

  • Query. Free text (case-folded, punctuation-stripped). Exact match by default; toggle match prefix for “winter” to also fire on “winter coat” etc.
  • Document. Pick from a typeahead over your indexed catalog. Out-of-stock SKUs are pickable but render dimmed.
  • Position. Slot 1, 2, 3, etc. Two pins for the same query at the same slot is a validation error.
  • Region. Optional. Blank = applies in every region. See Regions.
  • Lifetime. “Always on” or a date range. Expired pins auto-deactivate but remain in the list for audit; click Restore to re-arm.

Pins are evaluated at query time, after relevance scoring but before LTR re-ranking. That means a pinned doc still carries a real relevance score for analytics; you can A/B whether the pin is actually buying you conversion vs. the un-pinned ranker output (see below).

Boosts & deboosts

Less surgical than a pin, more durable. A boost says “documents matching this filter score higher (or lower) by this multiplier.” Typical uses:

  • Boost in-stock SKUs by 1.2× — out-of-stock items still rank but never displace an available alternative.
  • Boost a category for a query (e.g. “jacket” → boost category:Outerwear by 1.5×) when the ranker over-indexes on accessories.
  • Deboost discontinued SKUs by 0.5× while you wait for the catalog cleanup to ship.

Filters are the same shape as in tools/call search: any indexed field, any boolean expression. Boost/deboost rules are bounded — the rule engine clips multipliers outside [0.1, 10] to prevent one rule from completely flattening the ranker.

Global vs. per-query. Leave the query field blank to apply the boost on every search. The in-stock-boost above is a classic blank-query rule. Per-query boosts are useful for category-page searches ( “mountain bike” → boost category:Bikes).

Suppressions

Stronger than a deboost: suppressed documents simply don't appear in results. Reach for a suppression when a deboost is too soft (the SKU still surfaces on long-tail queries) or when you want a hard fence (legal, recall, adult content).

Two flavours:

  • Document suppression. Hide one SKU everywhere. One-row override.
  • Filter suppression. Hide everything matching a filter — e.g. brand:Discontinued while you finish a brand wind-down.

Suppressions are also audit-logged; the audit row carries the operator who applied it and a free-text reason field. Required for recall + compliance suppressions; optional otherwise.

A/B experiments

Every override above can be wrapped in an A/B experiment so you measure whether the change actually buys conversion before committing.

  1. Create the override as usual; toggle Run as A/B.
  2. Pick the split (default 50/50) and the duration (default 14 days, max 60).
  3. Seekmodo assigns each shopper a sticky cohort cookie. Variant A gets the override; variant B gets the un-overridden ranker.
  4. The experiment's dashboard (Merchandising → A/B) tracks CTR, conversion rate, and revenue per session per cohort. A statistical-significance flag flips when one cohort is meaningfully ahead.
  5. Click Promote to bake the winning variant into a permanent override, or Discard to drop both sides.

Surfaces affected

Merchandising overrides apply to:

  • Search — every POST /v1/search and tools/call search.
  • Recommendations — slots driven bytools/call recommend (related-products, frequently-bought-together).
  • Category pages — when your connector calls search with a category: filter (the default for Zen Cart, WordPress, WooCommerce, Shopify connectors).

Out-of-band typeahead and image-search live on slightly different code paths and currently only respect suppressions; pin / boost support in those surfaces is a roadmap item.

Cache & rollout

Saved overrides are visible in your storefront on the connector's next 5-minute config refresh. To force the cache to flush sooner (during a launch, say), most connectors expose a CLI:

# Zen Cart
php artisan seekmodo:config-refresh

# WordPress / WooCommerce
wp seekmodo refresh-config

# Shopify (admin)
shopify seekmodo config-refresh

See the per-connector docs under Connectors for the exact command shape.

Auditing

Every save writes a row in your tenant's merch audit log with the operator, the diff, the region, and a timestamp. Filter by operator or region to scope a review. Audit rows are retained for the lifetime of your tenant (vs. AI-Integration audit which rotates at 90 days).