The Maru Search Search API v1 (Pro plan) returns search results as JSON, with Japanese spelling variants, synonyms and filters already handled. You call /apps/marutto-search/search on the store's own domain, so no API key or CORS setup is needed. It works from any storefront page: the search results page, the header, collection pages, product pages, the cart and blog articles. It cannot be called from checkout or from outside the store (Hydrogen, native apps).
Your Shopify search results,in your design, anywhere in your store.
The Search API of the Shopify app Maru Search lets you place Japanese-aware search results anywhere in your store, from the header and product pages to the cart and blog articles, in your theme's own look. Shoppers find what they were looking for beyond the search results page.
An API that returns search results as JSON, included in the Pro plan ($49.99/month, 14-day free trial).See the live samples
Why search
People who search are ready to buy
People who type into the search box usually know what they want. If they find it they buy; if not, they go elsewhere. Third-party research shows the gap clearly.
- 44%
Visitors who searched were 24% of all visitors but drove 44% of total site revenue. They converted at 2.5 times the rate of non-searchers.
Source: Constructor, Beyond Relevance (113 retail sites, 609M searches, Oct–Dec 2024)
- 92%
When a search succeeds, 92% say they buy the item they were looking for (US consumers).
- 63%
63% of site-search users in Japan say a poor search experience on a brand's online store has made them give up a purchase (often 9.2% plus sometimes 53.7%).
Source: Scinable survey (1,030 EC users in their 20s–50s, Dec 2025)
These are third-party studies and do not show the effect of installing Maru Search. After you install it, you can check the effect in the admin under search-driven sales.
How it works
Maru Search returns results; you design the screen
Maru Search decides which products to show and in what order. Your theme decides which page shows them and how they look.
Maru Search decides
Which products, in what order
It breaks text into words and absorbs differences between hiragana, katakana and kanji, and full- and half-width characters. Synonyms, filtering, facet counts and ordering are handled by Maru Search too.
You build
Which page, and how it looks
Search results page, header, product pages, cart: where it goes and how it looks is up to you. A reference implementation that follows the spec lets you start by rewriting only the rendering.
Stays as it is
Your theme's design and layout
Maru Search only returns the search data (JSON) and never touches your theme's code. The look and the page structure stay your theme's.
Versus standard search
It differs from standard search in Japanese matching and where you can call it
Shopify has its own storefront search and search APIs. The standard option is the better fit in some cases, and we say so here too.
| Item | Shopify standard search | Maru Search Search API |
|---|---|---|
| Japanese matching | Shopify standard searchMatches runs of 3 or more katakana, hiragana or kanji characters (kanji also in pairs). | Maru Search Search APIBreaks text into words and absorbs hiragana, katakana and kanji differences by converting readings. |
| Searching in hiragana | Shopify standard searchIn 46 of 70 stores, the target products in the top results dropped to half or less of the original spelling (measured on stores without a search app). | Maru Search Search APIわんぴーす returns the same 8 results (products, article, page) as ワンピース (sample results checked on the real engine). |
| Suggestions while typing | Shopify standard searchJapanese is not among the supported languages of predictive search (Predictive Search API). | Maru Search Search APICall confirmed search with a small limit to show product and article suggestions while typing. |
| Where you can call it | Shopify standard searchThe Storefront API search query can be called from outside the store, such as custom storefronts built with Hydrogen. | Maru Search Search APIStorefront pages only (via the app proxy). It cannot be called from outside the store. |
| Price | Shopify standard searchIncluded in your Shopify plan. | Maru Search Search APIIncluded in the Maru Search Pro plan ($49.99/month). |
Stores whose shoppers search by Japanese product names fit the Search API; if you need to call search from outside the store, such as Hydrogen or an app, the Storefront API fits better.
Patterns
Place search results anywhere in your store
The Search API is not just for the search results page. It can be called from any storefront page. Here are six placements that tend to work, as live samples.
The sample store and products are fictional. Query results were checked against the real Maru Search engine.
A search results page that matches your theme
Build results from your theme's own components instead of the app's screen. Colors, materials, price range and on-sale counts arrive pre-aggregated, so filters are straightforward. When a search comes up empty, you also get what other shoppers searched next.
What it movesConversion from search
Pick a color or material and the results and counts update.
Results for “ワンピース”8 results
Show products and articles while the shopper types
Show product and article suggestions while the shopper is still typing. Words with a set destination, like 送料 (shipping), can go straight to that page.
What it movesSearch drop-off
Filter a collection by material or stock
Put a list on collection pages that filters by material, origin, brand and stock. Information in product metafields becomes a filter as is.
What it movesBrowsing and conversion
In-stock related products next to the one being viewed
Fetch products with the same material or tag, in stock only. Variant images and IDs come back too, so shoppers can pick a color and add to cart right there.
What it movesAverage order value
Just the right item for shoppers close to free shipping
Use the remaining amount as the minimum price and fetch in-stock products, cheapest first. Shoppers who are close to free shipping see one item that gets them there.
What it movesAverage order value
Product lists inside articles that follow your stock
Embed a keyword-based product list in articles or landing pages. Sold-out items drop out of the results, so you never have to swap them by hand after publishing.
What it movesSales from articles, and less upkeep
Start with one placement.
You don't need all six. Start with just the cart, or just the search results page. We're happy to help you decide where to begin.
Measurement
Sales from API-built screens show up in your admin
Send two events, one on search and one on result click, and Maru Search links add-to-cart and purchases, showing them under search-driven sales in the admin. Add placements as you see the effect.
01
On search
Send the same session_id as the search request, plus query_id and measurement_proof from the response.
02
On result click
Send the clicked product's product_id and its position in the results (0-based).
03
On add to cart and purchase
Nothing to send. The Maru Search Web Pixel re-attaches measurement_proof and links each sale to the search that led to it.
04
See it in the admin
It shows up in search-driven sales, click-through rate and the ranking of clicked products.
Without these two events, search still works but search-driven sales are not recorded. Requests without a session_id are not counted in analytics either.
Pricing
The Search API is included in the Pro plan
Pro plan
$49.99/ month
14-day free trial
The Search API is included in the Pro plan at no extra cost, with no usage-based billing by search volume. It is not available on Free or Basic.
Included in Pro (excerpt)
- Search API v1 (receive results as JSON, render in your own design)
- Purchase analytics, search-driven sales and improvement suggestions
- Search and filter by product metafields
- Custom synonym dictionary and per-query destinations
- Product boosts, field weights and per-keyword display rules
Implementation help
We can build it for you
As the developer of Maru Search, we design and build screens on the Search API. Tell us where you want it and your store URL.
- Custom search results and collection pages
- Header search, and product lists on product pages or in the cart
- Measurement events, through to checking search-driven sales
We quote after hearing what you need.
Getting started
Set it up in five steps
1
Pick a placement
Look through the patterns and choose one place to start. Ask us if you are unsure.
2
Read the spec
The spec and reference implementation (search-api-sample.js) are open without installing.
3
Sync on the Pro plan
Install and start the Pro free trial to begin building the product index. When degraded: true stops coming back, you are ready.
4
Render and send the events
Replace the reference rendering with your design and send marutto_search and marutto_result_clicked.
5
Watch search-driven sales
Check sales from search in the admin and add placements as you go.
The free trial lasts 14 days. Decide the placement and design first, and you can see the effect within the trial.
For developers
What to know before you build
These are the parts of the spec people trip over most. See the spec for full definitions.
Key facts
- Endpoint
- /apps/marutto-search/search (on the store's own domain, via Shopify's app proxy)
- Auth
- None. Shopify's signature identifies the shop; no API key or CORS setup
- Required
- type=search, contract=v1, q (use * for all), session_id
- Response
- JSON: product, article and page results, facet counts, total, offset, limit
- Paging
- Up to 50 per request; offset up to 2,000
- Rate limits
- Per 10 seconds: 50 per shop, 20 per visitor (type=search)
- Speed
- Search p95 of 100–250 ms (production, Aug 2026; runs in Tokyo)
- Stability
- v1 is kept for at least 12 months, with 6 months notice before retirement
- Not available
- Checkout, thank-you and order status pages, outside the store (Hydrogen, native apps)
- Plan
- Pro ($49.99/month, 14-day trial). Not on Free or Basic
No API key, no CORS setup
The endpoint is /apps/marutto-search/search, a URL on the store's own domain (a Shopify app proxy), so Shopify's signature identifies the shop.
Always send contract=v1
Only requests with it are guaranteed the documented shape. v1 is kept for at least 12 months, with 6 months' notice before retirement. New fields are added within v1.
Always check degraded
During the first sync after install, degraded: true comes back with empty results. Every new store goes through this on day one, so plan a “getting ready” message or a switch to Shopify's standard search.
Don't send on every keystroke
type=search allows 20 requests per visitor per 10 seconds. When calling as the shopper types, wait 250–300 ms first, and use the echoed query to drop stale responses.
offset caps at 2,000
Show “load more” only when the next offset is below both total and 2,000. Checking total alone keeps appending the same products.
Some places are off-limits
It can't be called from checkout, the thank-you page or the order status page, nor from outside the store, such as Hydrogen on its own domain or native apps.
Two measurement events
Send one on search and one on result click, with the same session_id as the search request. The Maru Search Web Pixel links add-to-cart and purchases.
// On search
Shopify.analytics.publish("marutto_search", {
query: data.query,
query_id: data.query_id,
session_id: sessionId, // same value as on the search request
measurement_proof: data.measurement_proof,
result_count: data.total,
});
// On result click
Shopify.analytics.publish("marutto_result_clicked", {
query_id: data.query_id,
session_id: sessionId,
measurement_proof: data.measurement_proof,
product_id: item.product_id,
position: index, // 0-based
});Day one, and stores not on Pro
A new store returns degraded: true until its index is built. Plans other than Pro get a 403 with code: plan_required. Neither means search is broken, so don't show shoppers an error.
SALEリネンブレンド ロングワンピース
コットン シャツワンピース
ティアード ロングワンピースOnce the index is ready, results come back in the documented shape.
FAQ
Questions we often hear
Which plan includes the Search API?
The Pro plan ($49.99/month), with a 14-day free trial. It is not available on Free or Basic.
Can I customize the Shopify search results page to match my design?
Yes. The Maru Search results page has about 50 appearance settings in the admin, with no code. To build it from your theme's own components instead, receive results as JSON from the Search API and render them in your code.
How is it different from the Storefront API search?
The Storefront API search query is Shopify's standard API and can be called from outside the store, such as Hydrogen. The Maru Search Search API can only be called from storefront pages, but it absorbs hiragana, katakana and kanji differences by converting readings and handles search-driven sales measurement. If you need to call search from outside the store, the Storefront API fits better.
Can I use it alongside the Maru Search search screen?
Yes. For example, keep the app's search results page and build only the product-page recommendations with the Search API.
Can we use it without someone who writes theme code?
Rendering with the Search API has to be implemented in your own code. If nobody in-house can write it, talk to an agency or to us. If you'd rather not write code, the app's own search screen is the quickest route.
If you build it, what does it cost and how long does it take?
It depends on the number of placements and the design, so we quote after hearing what you need. Starting with a single placement is welcome.
What happens to what we built if we leave the Pro plan?
The Search API is a Pro feature, so requests start getting a 403 (code: plan_required). If you build it like the reference implementation, falling back to the theme's standard search, shoppers see no error.
Can I call it from Hydrogen or a mobile app?
Not at the moment. The Search API works only on the store's own domain via the app proxy. If you'd like to use it from Hydrogen on its own domain or a native app, let us know.
Can I use it inside checkout?
No. Shopify checkout extensions run in a sandbox with restricted network access. The thank-you and order status pages are the same. The cart page and cart drawer are fine.
Will spec changes break what we build?
v1 is kept for at least 12 months, with 6 months' notice before retirement. Published field names, types and meanings, and event names, will not change. New fields are added within v1; breaking changes will ship as v2.
Are prices tax-inclusive? What about multi-currency stores?
Prices come back in the shop's base currency, tax-inclusive or not per your Shopify settings. With Shopify Markets multi-currency, they won't match the shopper's currency. Don't convert with exchange rates; render prices only when the base and display currencies match.
What's needed to record search-driven sales?
A session_id on every search request, plus two events sent with Shopify.analytics.publish: marutto_search on search and marutto_result_clicked on result click. The Maru Search Web Pixel links add-to-cart and purchases automatically.
About this page
Updated September 27, 2026. Based on the Search API v1 spec.
Provided by Pepin, the developer of Maru Search.
Search, anywhere in your store.
Try the Pro plan free for 14 days. The spec and reference implementation are open to read without installing.