Seekmodo developer docs

← Back to Connectors

Installing the Seekmodo Zen Cart connector

This guide assumes:

• You have a Seekmodo subscription at seekmodo.com/pricing.
• Your storefront is on Zen Cart 1.5.7+ (1.5.7 supported since connector v1.3.19).
• You have admin access to your Zen Cart store.

If something goes sideways, see Troubleshooting.

0. Recommended PHP extensions

The connector self-checks the PHP environment and surfaces the result on Tools → Connect to Seekmodo (under Diagnostics), once paired. None of these are install-time gates — the plugin loads on PHP 7.4+ regardless — but each one matters for steady-state behaviour. Skim this list before install so the diagnostics panel is boring on day 1.

Quick check from the host:

php -v                                # need >= 7.4
php -m | grep -E 'sodium|apcu|opcache|curl|openssl|mysqli|intl'

If apcu is missing on cPanel / EasyApache 4:

yum install -y ea-php81-php-pecl-apcu     # adjust ea-phpXX to your runtime

If apcu is missing on Debian / Ubuntu:

apt-get install -y php8.1-apcu            # adjust 8.1 to your runtime
phpenmod apcu
systemctl restart php8.1-fpm apache2      # or nginx

If you're on managed hosting without shell access, paste this ticket into your provider's support form (replace the version):

Subject: please enable the apcu PHP extension

Hello — our Zen Cart storefront uses the Seekmodo connector, which expects APCu to be loaded with apc.enabled=1 (and apc.enable_cli=1 if cron tasks call PHP directly). Could you install the php-pecl-apcu package for our PHP runtime and confirm php -m | grep apcu shows the extension loaded? Thanks.

After install, refresh Tools → Connect to Seekmodo; the APCu row in the Diagnostics table should flip from yellow to green.

1. Download the plugin

Always download the signed zip from the Zen Cart plugin page (that page always shows the current release). For scripting, read the latest version from seekmodo.com/plugins/manifest.json:

# Replace VERSION with platforms.zen_cart.latest from manifest.json
VERSION=1.3.29
curl -fLO "https://seekmodo.com/plugins/seekmodo-zen-cart-v${VERSION}.zip"
curl -fLO "https://seekmodo.com/plugins/seekmodo-zen-cart-v${VERSION}.zip.sha256"
sha256sum -c "seekmodo-zen-cart-v${VERSION}.zip.sha256"
# expected: seekmodo-zen-cart-v${VERSION}.zip: OK

A signed release zip is typically ~300–370 KB and expands to ~1 MB under zc_plugins/Seekmodo/v<X.Y.Z>/. If you see tens of megabytes after unzip, you likely extracted into your whole storefront tree or grabbed the wrong archive.

Don't grab the zip from a third-party mirror. Numinix.com publishes a mirror with a separate signing chain; any other source is unverified. Prefer the Seekmodo.com download when the two disagree.

2. Install through Zen Cart's Plugin Manager

1. Log in to your Zen Cart admin (/admin or your renamed admin path).
2. Go to Tools → Plugin Manager.
3. Click Upload New Plugin and select the downloaded zip.
4. Find the row labelled Seekmodo in the listing and click Install.
5. Approve the install confirmation. The Scripted Installer will:
   • Create the Seekmodo Search configuration group.
   • Seed 13 NUMINIX_SEEKMODO_* configuration rows with safe defaults (MODE=off, AUTO_PROMOTE=true, TIMEOUT_MS=250, etc.).
   • Hide the configuration group from the admin sidebar by default — once paired, settings live on admin.seekmodo.com.

After install, the row should read Seekmodo v<latest> — Installed (for example Seekmodo v1.3.29 — Installed).

Upload alone is not enough. Zen Cart stages the zip on upload, but catalog-root callback shims (see below) are not live until you click Install (first time) or Update / Upgrade (existing row).

2a. Zen Cart 1.5.7, subdirectory catalogs, and file-only installs

Use this section if you are on Zen Cart 1.5.7, copied zc_plugins/Seekmodo/ by FTP/git/rsync, or run the catalog from a subdirectory such as /shop/.

Pairing posts credentials to a catalog-root URL:

https://<host><DIR_WS_CATALOG>numinix_seekmodo_pair_callback.php
# e.g. https://www.example.com/shop/numinix_seekmodo_pair_callback.php

Plugin Manager Install or Upgrade copies these shims into your catalog root (same directory as index.php):

• numinix_seekmodo_pair_callback.php — required for Connect to Seekmodo
• numinix_seekmodo_suggest.php, numinix_seekmodo_push_catalog.php, and the other top-level numinix_seekmodo_*.php files in the plugin's catalog/ folder

Subdirectory catalogs are fine — register the apex domain in Seekmodo admin (e.g. example.com), not the /shop/ path.

On Zen Cart 1.5.7, prefer Plugin Manager Upload → Install/Upgrade over Tools → Seekmodo Updates → Apply update alone; the in-plugin auto-updater may not redeploy catalog-root shims on older cores.

Verify before pairing:

curl -s -X POST "https://www.example.com/shop/numinix_seekmodo_pair_callback.php" \
  -H "Content-Type: application/json" -d "{}"

Expect JSON such as {"ok":false,"error":"empty body"}. If you get your storefront homepage HTML instead, redo Install/Upgrade or manually copy the shims from zc_plugins/Seekmodo/v<X.Y.Z>/catalog/ into your catalog root, then pair again.

3. Pair the storefront with your Seekmodo tenant

This is the one-click flow that round-trips your tenant ID and HMAC secret without any copy-paste.

1. In Zen Cart admin, go to Tools → Connect to Seekmodo.
2. Click Connect. The page redirects you to https://seekmodo.com/connect?install_token=…&callback=… with a one-time token.
3. Sign in to seekmodo.com (if you're not already), pick the tenant to bind to, and approve.
4. Seekmodo redirects you back to your storefront's pair-callback URL carrying a signed payload that the plugin verifies against the public JWKS at https://seekmodo.com/.well-known/jwks.json.
5. On success, the plugin populates NUMINIX_SEEKMODO_TENANT_ID and NUMINIX_SEEKMODO_SHARED_SECRET in your Zen Cart database. The page shows a green "Paired" banner.

If anything fails, you'll see the cause inline — the most common is a clock skew of more than 5 minutes between your Zen Cart host and the gateway. NTP is your friend. See Troubleshooting for the per-symptom playbook.

4. Flip from off to Learning or Active

Open admin.seekmodo.com, find your tenant, and switch Mode from Disabled to Learning or Active. The connector polls tenant.snapshot every 5 minutes (more often when you've just paired); within that window your storefront starts using Seekmodo.

If you are on Learning / shadow and search "looks wrong": that is expected — the SERP is still native Zen Cart. Flip Mode to Active when you are ready for shoppers to see Seekmodo ranking. You can switch back to Learning any time without reinstalling.

On a brand-new install, Active self-promotes from shadow to enforce after about 50 successful storefront searches with the gateway healthy. You can watch the promotion in <docroot>/logs/numinix_seekmodo.log if NUMINIX_SEEKMODO_DEBUG=true.

Use the Mode control on admin.seekmodo.com (Overview or Settings). Changes write to the gateway and the connector picks them up within about five minutes — or click Refresh snapshot on Zen Cart Tools → Connect to Seekmodo.

5. Day-two checklist (catalog, languages, tuning)

After pairing, most merchant work happens in admin.seekmodo.com, not in Zen Cart configuration screens.

1. Index the catalog. After Mode is Active (or Learning), open Zen Cart Tools → Connect to Seekmodo, click Refresh snapshot, then Push catalog now (v1.3.31+; or run php numinix_seekmodo_push_catalog.php --ack-quota from the catalog root). Watch logs/numinix_seekmodo_indexer.log. Empty or stale indexes look like "search is broken" even when the connector is healthy.
2. Confirm languages. Suggest labels follow the shopper's Zen Cart language (English / German / deutsch / Spanish / French packs ship in recent plugin releases). Catalog text is indexed from the store's default language unless you use Regions on a higher plan — keep German as the Zen Cart default if that should be the primary indexed language.
3. Tune relevance without code. In admin: synonyms, pins, redirects, banners, and deboosts. Changes apply on the next gateway snapshot pull (usually within a few minutes).
4. Watch Analytics. Top queries, Zero results, and Top clicked products tell you what to fix before (and after) leaving Learning.

6. Verify

Three checks. Two manual, one scripted.

Plugin Manager smoke

Admin → Plugin Manager: row reads the version you installed (for example Seekmodo v1.3.29 — Installed).

Storefront smoke

Search for a known product on the storefront. Tail <docroot>/logs/numinix_seekmodo.log while running the search:

2026-05-30T18:14:07Z  search backend=gateway  mode=enforce  ms=84  hits=12  status=200

In Learning / shadow you should still see gateway log lines, but the HTML SERP stays native. In Active / enforce expect backend=gateway. If the line says backend=native or doesn't appear at all, see Troubleshooting.

Gateway-side telemetry

Sign in to admin.seekmodo.com, open Analytics → Top queries, and confirm your test search appears. Click events arrive within ~5 seconds.

7. Recurring maintenance

There isn't much. The plugin pulls policy from the gateway in real time, the indexer runs from your existing Zen Cart cron, and the circuit breaker handles transient gateway issues automatically.

When a new release ships, you'll receive an email from [email protected]. Re-run the Upload New Plugin flow with the new zip — the Scripted Installer detects the existing version and upgrades cleanly, preserving config rows. Prefer seekmodo.com/plugins/zen-cart for the signed package.

The Zen Cart connector is open source — browse the source on GitHub if you want to file an issue or send a PR.