Glossary

What the words in this documentation mean.

Contract (contract=v1)

A request to be answered in the shape this documentation describes. Only requests carrying contract=v1 are guaranteed that field names, types and meanings will not change.

Without it you get the app's internal response — the shape our own widget reads, which changes without notice.

Facets (facets)

The filter options and their counts — the aggregates behind "Vendor: ATELIER NOA (42)".

Think of them as the raw material for the filter menu beside the results.

"facets": {
  "vendors": [{ "value": "ATELIER NOA", "count": 42 }],
  "price_range": [3900, 42000]
}

Degraded (degraded)

The index is temporarily unusable — during a first sync, or an outage.

While degraded, results are empty or come from Shopify's own search. It is not an error: code that reads data.results keeps working.

Browse (q=*)

Listing everything with no search term, for screens like a collection page where shoppers filter rather than search.

It reads only the products table, so some facets are not returned.

Morphological analysis

Splitting Japanese text into words. Japanese has no spaces between words, so without this, ワンピース (dress) would not find 春夏用リネンワンピース.

Spelling variants

Different ways of writing the same thing — りんご / リンゴ / 林檎, or ＷＤ６５０ / WD650.

Marutto Search absorbs these with no configuration (see How search works).

Synonyms

Words that mean the same thing but share no characters — Tシャツ / カットソー.

Unlike spelling variants these cannot be derived automatically, so they are registered in the admin (Pro).

App Proxy

A Shopify mechanism that forwards requests made to a URL on the store's domain to the app's server.

It is what makes https://store.myshopify.com/apps/marutto-search/search — the store's own URL — work without an API key or CORS configuration.

measurement_proof

The signature that ties a search to a purchase. Including it in the analytics events is what lets us trace which search led to a sale.

Without it, that store records no search-attributed revenue (see §7 of the specification).

session_id

An identifier grouping one shopper's actions. You generate it.

It ties searches to clicks, so it must not change as the shopper navigates. A search without one is excluded from analytics.