NP Search — Documentation

Everything you need to install, configure, and get the most out of NP Search on your Shopify store.

1. Install

Prefer a guided walkthrough? Watch the 3-minute installation and first-improvement tutorial. It uses the current NP Search storefront and merchant admin.

1. Visit the NP Search listing on the Shopify App Store and click Add app.
2. Approve the read-only permissions (product catalog + inventory).
3. You'll land on the Install guide page inside your Shopify admin.
4. Your product catalog syncs automatically in the background — usually within 60 seconds.
5. Click Activate NP Search, confirm the App Embed is enabled, and click Save in Shopify's theme editor.

Return to the NP Search Dashboard. Storefront readiness confirms both the catalogue and published theme are ready, then lets you open the real shopper experience in one click.

2. Activate on your theme

The App Embed is the required activation step. It connects NP Search to your theme's existing search icon, native search fields, mobile trigger, and keyboard shortcut. The optional section block below adds another visible placement but does not replace App Embed activation.

App Embed Block (recommended)

In the Shopify theme editor, open App embeds in the left panel, find NP Search Overlay, and toggle it on. Click Save. App Embeds work on Online Store 2.0 and vintage themes. One click activates it; one click removes it.

Optional: add NP Search as a section block

In the theme editor, open any section (for example the header), click Add block, and pick NP Search. This places a visible search bar inline in that section. No theme code changes required.

Keyboard shortcut

⌘K (Mac) / Ctrl+K (Windows/Linux) works from any storefront page after the App Embed is enabled and saved.

3. Feature walkthrough

Storefront experience and brand controls

Open Settings → Storefront experience to choose Classic, Studio, or Fashion, switch between Focused and Advanced layout, and set a six-digit brand colour. The live preview shows buttons, selected filters, prices, focus states, product details, and content results before you save. NP Search automatically chooses readable button text for the selected colour.

Each shopper-facing feature can be controlled independently: Add to cart, predictive products, quick add, pages and blog articles, zero-result recovery, the pre-query discovery shelf, vendor, SKU, price, availability, powered-by label, and the whole filter interface.

Search relevance tuning

In the admin, go to Settings. Adjust weights for title (default 10), SKU (8), product type (7), tags (5), vendor (4), and description (3). Higher means more influence on keyword ranking. Under AI ranking, every merchant can enable semantic intent, choose a bounded 0–100 influence setting (30% is the balanced default), and enable learning-to-rank from exactly attributed engagement. Verify representative queries in Search Lab before keeping a large change.

Search Lab: understand and fix ranking

Open Search Lab and run the exact words a shopper uses. Lab searches never enter storefront Analytics. For every product you can see its keyword rank, semantic rank and similarity, stock tier, strongest scoring signals, learning contribution, and any merchandising rule that changed the result.

Use Adjust beside a product to open a prefilled rule for that query and product. Review Pin, Bury, Boost, or Filter, save it, then return to Search Lab and run the query again. This creates a safe diagnose → adjust → verify workflow without experimenting on shoppers.

Smart precision guard automatically removes low-confidence vendor-only or weak semantic noise when the catalogue already has clear matches. Search Lab lists every protected product and why it was excluded. If it belongs in the result, choose Pin anyway, review the prefilled rule, and save. Exact brand searches and high-confidence semantic matches are preserved automatically.

In Settings → Relevance weights, Product type has its own weight alongside Title, SKU, Tags, Vendor, and Description. You can also turn Smart precision guard off, although the default is recommended for cleaner shopper results.

Synonyms

Bidirectional word pairs — "sneakers ↔ trainers" means a search for either finds products matching the other. Seed 178 curated pairs across electronics, fashion, beauty, home, and fitness with one click in Settings → Seed packs. Add your own pairs as you notice gaps.

Merchandising rules

In Merchandising rules, build a rule for a search query or a Shopify collection. Choose exact products or dynamic conditions such as vendor, tag, collection membership, stock, and price. The builder previews the production ranking before anything is saved, and Verify in Search Lab tests the same unsaved draft safely.

• Pin — force a product to the top of results for a given query.
• Bury — drop a product to the bottom.
• Boost — add a score bonus (fine-grained control).
• Hide — exclude a product entirely.
• Banner — place a campaign message above matching results.

Schedule with start/end dates for promos and seasonal pushes.

Query redirects

Send specific queries to landing pages. Example: "gift card" → /pages/gift-cards. The storefront overlay surfaces a redirect card above results.

Predictive commerce and recovery

Predictive products are an optional typing aid while the full result grid is loading. Only published, in-stock products are eligible. Simple products can use Quick Add; products with choices keep a safe View options action. Product opens, adds, orders, and revenue stay separate from completed search activity in Analytics.

Zero-result recovery records the original search as a real miss, then can offer popular in-stock products. The optional pre-query shelf uses shop-specific product opens, adds, and purchases before a shopper types. Recovery and discovery outcomes never inflate search volume.

Collection Page Filters

Open Collection filters, choose a Shopify collection, and select its visible price, availability, vendor, product option, and catalogue-specific groups. Add NP Collection Filters to a collection template in the theme editor. If the enhanced request cannot load, the original theme collection grid remains available automatically.

Analytics

The dashboard is a revenue command center for search revenue, recovered revenue, and directional revenue at risk. Profit opportunities prioritizes repeated zero-result and no-engagement searches and opens each problem directly in Search Lab. Money estimates appear only after a conservative baseline exists for the current shop.

Drill into Analytics for:

• Top queries — exact engagement, clicks, direct adds, and purchases without double-counting.
• Zero-result queries — ripe for synonym additions.
• No-engagement queries — returned results but produced no click, direct add, or purchase.
• Search revenue — completed search-assisted orders, purchase rate, and revenue by currency.
• Daily trend chart — searches, clicks, cart searches, and purchased searches overlaid.

Analytics history is retained for up to 180 days on every current plan. Turning off optional storefront analytics stops query and engagement collection, while anonymous query-free usage metering continues so allowances and Shopify billing remain accurate.

4. Plans & billing

	Free	Pay as you grow
Price	$0	$1/month + $0.002 per committed unique search ($1 per 500)
Committed searches	1,000 per rolling 30 days	Usage based
Product-count charge	None	None
Keyword + fuzzy search	✓	✓
Synonyms + 6-language stemming	✓	✓
Semantic and image search	✓ within allowance	✓ within cost guard
Learning-to-rank	✓ within allowance	✓ within cost guard
Merchandising rules + redirects	Unlimited	Unlimited
Focused + Advanced layouts	✓	✓
Analytics history	Up to 180 days	Up to 180 days
Support	Email	Email

What counts once: one submitted text or voice query, or one successfully processed image-search intent, identified by a unique search ID.

What does not create another charge: autocomplete keystrokes and previews, filters, sorting, pagination, retries, zero-result recovery, discovery shelves, and merchant tests in Search Lab.

The Free allowance uses a rolling 30-day window. After it is reached, keyword search, rules, redirects, filters, and the chosen layout continue, while compute-heavy semantic ranking, learning-to-rank, image search, and related-product enrichment pause until usage returns below the allowance or you switch to Pay as you grow.

Paid merchants can set a spending threshold under Plan & billing. Choose notification-only, or keyword-continuity mode at the threshold. This is an app-level protection based on rolling usage; Shopify remains the system of record for charges and invoices. Legacy fixed-price Starter, Pro, and Plus subscriptions remain grandfathered until the merchant explicitly switches.

5. FAQ

Does NP Search replace Shopify's default search?

When the App Embed is enabled, NP Search takes over the theme search icon, native search fields and search-form submissions so shoppers stay in one stable full-screen experience. Direct URL hits such as /search?q=iphone remain compatible with Shopify.

What happens if a shopper presses Back or refreshes?

Back closes NP Search before leaving the underlying storefront page. Forward or refresh restores the active query and its products. The query is kept only in short-lived storage for that browser tab; it is never added to the storefront URL or browser history state.

How long does indexing take?

Initial sync: 1-5 minutes for up to 10,000 products. After that, webhooks keep the index fresh within seconds of any product change.

Does it work with custom themes?

Yes. The App Embed works with Online Store 2.0 and vintage themes. The optional inline section block requires an Online Store 2.0 section that accepts app blocks.

What languages does it support?

Stemming works for English, Spanish, French, German, Italian, and Portuguese. Choose the language used by your product titles and descriptions under Settings → Relevance weights → Primary catalog language; Search Lab shows the language used for every test. Storefront labels independently follow each shopper's active Shopify language. Semantic search also handles mixed-language intent well.

Do I need to send you an OpenAI or Anthropic key?

No. Semantic search runs on a local MiniLM model on our servers, so you do not need an external LLM account or API key. Submitted shopper searches still follow the NP Search usage pricing described above.

Does NP Search work on mobile?

Yes. Mobile uses the same full-screen search, a two-column product grid and a dedicated filter drawer. It follows the visible viewport when the on-screen keyboard or browser bars change size, so the search field, complete result summary and controls stay usable without horizontal clipping. The drawer keeps keyboard focus and collapsed groups stable while counts update, then offers a bottom Show N results action. A persistent 44 px Close button is always available; Android Back and iOS swipe-back also dismiss search before leaving the shopper's current product or collection page.

Which storefront filters can shoppers use?

NP Search automatically builds product-option filters such as color, size, vendor and type. It also includes exact Price range and In-stock only filters on every plan. Under Settings → Storefront experience, you can turn off the entire filter interface, choose individual product-option groups, or independently hide price and availability filtering.

Can I change the search colors and layout?

Yes. Under Settings → Storefront experience, choose Classic, Studio, or Fashion, select a recommended colour or enter your own hex value, choose Focused or Advanced layout, and preview the result before saving. Every current plan includes every template and layout.

Can search include pages and blog articles?

Yes. Turn on Include pages and blog articles in search under Storefront experience. NP Search uses Shopify's native storefront index for matching content and does not store the page or article body.

Can I see which filters shoppers actually use?

Yes. Analytics → Filter impact shows completed applications for built-in and product-option filters, unique filtered searches, average result count, exactly attributed engagement, direct adds, and purchases. Tracking is first-party and anonymous; a filter event is counted only after its results load successfully.

How does purchase and revenue attribution work?

NP Search connects Shopify's consent-aware Web Pixel. A direct result-card add carries private random search metadata; a product click creates a bounded per-shop touchpoint for up to seven days. At checkout completion, only purchased lines matching those anonymous search touches are reported. Customer names, emails, phone numbers, addresses, payment data, and unrelated order lines are never sent.

The Pixel sends that allowlisted outcome to a shop-isolated, signed NP Search endpoint, so attribution also works when the storefront is password-protected or access-gated. The endpoint token identifies the installed shop, not a shopper, and contains no customer or order data.

Can I see the relevance score for each result?

Yes. Open Search Lab in the app. It shows the final score plus the evidence behind it; shoppers never see diagnostic scores.

What happens to my data if I uninstall?

All data tied to your shop is deleted within 48 hours. See our Privacy Policy.

6. Troubleshooting

"No results found" for queries I expect to work

1. Confirm the product is published to the Online Store channel. Draft and archived products are not indexed.
2. Check the Analytics → Zero-result queries table for the exact query. If it's there, consider adding a synonym.
3. Re-trigger index sync: Settings → Re-sync catalog.

Search icon in my theme doesn't open NP Search

Your theme's search element likely uses a non-standard selector. NP Search matches [data-np-search-trigger], .header__search, and [aria-label*="search"]. For custom themes, either:

• Add data-np-search-trigger to your theme's search element, or
• Email info@neuroplugin.com with your theme name — we'll help.

Semantic search isn't finding what I expect

Open Settings → AI ranking and check that Semantic intent ranking is enabled. Also check Plan & billing to confirm the store is not currently in keyword-continuity mode after reaching its Free allowance or configured paid cost guard. NP Search admits only sufficiently similar semantic candidates, fuses semantic and keyword ranks, and applies the precision guard when clear catalog matches already answer the query. Use Search Lab to inspect similarity and tune the influence setting instead of guessing.

My usage or Shopify charge looks wrong

Open Plan & billing to compare the rolling 30-day committed-search count and projected app charge. Remember that autocomplete, filters, sorting, pagination, retries, recovery surfaces, and Search Lab do not add billable searches. Shopify remains the invoice system of record. If the numbers still differ, email support with the shop domain and billing period; do not send shopper personal information.

Overlay styling conflicts with my theme

NP Search uses a scoped CSS namespace (.nps-*) to reduce theme conflicts. If a theme still changes the search layout, email us the theme name, storefront URL, and a screenshot so support can reproduce the issue.

7. Contact support

Email: info@neuroplugin.com — response within one business day.
Privacy / data requests: info@neuroplugin.com
Legal / abuse: info@neuroplugin.com

We're a small, independent team based in Spain. Real humans read every email.