Seekmodo

Seekmodo developer docs

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

← Custom connector guide · Automotive parts solution · REST · Fitment

Vehicle fitment for custom connectors

Seekmodo ranks and filters parts catalogs by vehicle — year / make / model garage, optional VIN decode, Vehicle Landing Pages, and fitment-aware recommendations. First-party BigCommerce and Zen Cart connectors ship widgets; any platform can implement the same contract over REST or MCP.

Prerequisites: a working custom connector loop (credentials, index, search, events) from /docs/connectors/custom. Request bodies: Fitment & vehicles in REST OpenAPI.

Mental model

  1. Product documents in Typesense carry fits_vehicles: int[] (vehicle ids this SKU fits) and optional universal_fit: bool (oils, cleaners, tools).
  2. Per-tenant taxonomy maps shopper YMM (and VLP slugs) to those vehicle ids via vehicle_taxonomy.bulk_upsert.
  3. Shopper APIs resolve YMM → id (fitment.resolve) then hard-filter search (search.by_vehicle).
  4. Optional central Seekmodo vehicle catalog + fitment.assignments.* for merchants who assign products against Seekmodo's global ids — see operator tooling; most custom connectors start with paths 1–3 only.

1. Index product fitment fields

On each product document sent to POST /v1/index, include:

{
  "id": "SKU-12345",
  "title": "Example brake pad set",
  "fits_vehicles": [1001, 1002, 1044],
  "universal_fit": false
}
  • fits_vehicles — integer vehicle ids from your taxonomy (or Seekmodo central ids if you use assignments + projection).
  • universal_fit: true — product remains discoverable without a garage vehicle; recommendations often OR this flag with the vehicle filter.

If the collection lacks fits_vehicles, search.by_vehicle returns an empty result set with meta.fits_vehicles_unavailable: true — fix the schema / indexer before blaming ranking.

2. Sync the vehicle taxonomy

Push rows with vehicle_taxonomy.bulk_upsert (max 1,000 rows per call). Typical fields:

  • vehicle_id (int, required)
  • year_start / year_end (or single-year ranges)
  • make_name, model_name (and optional make / model ids)
  • slug — precomputed Vehicle Landing Page slug
  • product_count — how many fitted SKUs you know about

After a full rebuild, prune stale vehicles with vehicle_taxonomy.prune using the same cutoff pattern as catalog prune. This projection powers fitment.resolve, picker options, and VLP / sitemap lookups — it does not by itself put fitment into Typesense; product fits_vehicles still comes from your indexer.

Resolve: POST /v1/fitment.resolve

{ "year": 2019, "make": "Honda", "model": "Civic" }

Response (match): { resolved: true, vehicle: { vehicle_id, year, make, model, label, slug, product_count } }. No match: { resolved: false, vehicle: null }.

Search: POST /v1/search.by_vehicle with either vehicle_id or a YMM triple. Optional free-text q refines within the fitted set (e.g. "brake pad"). Prefer a resolved vehicle_id — the gateway then hard-filters fits_vehicles:=<id>. Passing only YMM (without an id) is exploratory: the gateway filters on fits_year / fits_make / fits_model when those fields exist, not on fits_vehicles. Collections that index only fits_vehicles must resolve YMM to an id first (via fitment.resolve or your own taxonomy).

Legacy alias search.byVehicle still works; prefer search.by_vehicle.

4. Shopper picker and VLPs

Persist the shopper's selected vehicle_id in your session / garage cookie and pass it into search and recommend calls.

5. VIN decode

The gateway does not expose a VIN decoder tool. Decode in your connector or Worker (for example NHTSA vPIC), map to year / make / model (and optionally engine), then call fitment.resolve → search.by_vehicle. Stamp the cart or order with the vehicle id for support and analytics.

6. Recommendations with garage context

Use the recommend tools (recommend.related, recommend.also_bought, …) with an extra Typesense filter, for example:

filter_by: "fits_vehicles:=1001 || universal_fit:=true"

Same pattern works when enhancing ordinary search with a soft or hard fitment clause once the garage is set. REST: Recommendations.

7. Central catalog and CSV assignments (optional)

Seekmodo maintains a global vehicle catalog for marketplace tenants. Connectors can:

Operators then project taxonomy for the tenant. Custom connectors that already own a local fitment graph usually skip this and only push taxonomy + fits_vehicles.

Verification

  • Resolve a known YMM → non-null vehicle_id.
  • search.by_vehicle returns only fitted SKUs; a deliberately wrong vehicle returns empty or near-empty.
  • Universal-fit SKUs still appear when you OR universal_fit:=true.
  • Coverage / orphans: fitment.coverage, fitment.orphans (operator diagnostics).

First-party platforms