Migrating from Legacy Autocomplete to Suggestion Endpoints

The legacy autocomplete endpoint is deprecated. If your custom search integration
still calls it, you need to move to the supported suggestion endpoints, which power
Tweakwise's current as-you-type search experience.

This guide answers one question: how do you replace legacy autocomplete calls with
the current suggestion endpoints without breaking your search bar? You'll map the old
single-call model onto the two request families Tweakwise uses today, wire them into
your input, and render the grouped results.

The migration has three parts:

1. Split your single legacy call into the two current request families — regular
   suggestions (search phrases, categories, attribute filters) and item
   suggestions (products, blogs, content pages).
2. Render each group with the correct navigation target.
3. Re-apply the input hardening (debounce, request cancellation) around the new calls.

Do these in order. The rendering and hardening steps are the same regardless of which
integration path you take.

Implementation

Tweakwise splits as-you-type suggestions into two request families. Send both while the
user types and merge the results in your UI:

• Regular suggestions — search phrases, category suggestions, and attribute/filter
  suggestions.
• Item suggestions — product, blog, and content-page suggestions.

Unlike the legacy autocomplete flow, suggestions do not inherit configuration. A
suggestion targeted at a specific category will not fall back to a parent category's
configuration. Set up one configuration that covers your whole instance, or as few
configurations as possible — this is the biggest behavioural difference to plan for when
migrating off autocomplete.

See Suggestions for the canonical reference, and Building the frontend for the end-to-end frontend pattern this guide follows.

API approach

Follow the search-bar build described in the frontend guide, replacing your single
autocomplete request with the two request families:

1. Fire both request families while typing. On each qualifying keystroke, call the
   regular suggestions request and the item (product) suggestions request.
2. Render the groups from the regular suggestions response:
   • Search phrase suggestions navigate to the search page.
   • Category suggestions navigate to the specific category.
   • Facet / attribute suggestions apply the corresponding filter.
3. Render the item suggestions. Clicking a product goes to that product's detail
   page. Item suggestions return the standard item shape (itemno, type, title,
   price, brand, image, url) — see Items. Use itemno to enrich with any product data Tweakwise doesn't return.
4. Submit navigates to the search page with the typed term as the search query.

Implementation tips

Re-apply the input hardening from the frontend guide around the new calls:

• Debounce / throttle input events so you don't fire a request on every keystroke.
• Cancel in-flight requests — when the user keeps typing, only render the response
  for the latest request.
• Persist recent search terms to the user's storage and show them on focus when the
  input is empty; fall back to popular terms when there are none.

Migrating an existing integration: keep your current search-bar markup and event
wiring. Swap only the request layer — one legacy autocomplete call becomes the two
suggestion request families — then update your rendering to handle the grouped
response.

Notes

• Autocomplete is deprecated — treat this as a required migration, not an optional
  refactor. New work should target the suggestion endpoints from the start.
• No configuration inheritance. This is the most common migration surprise: a
  per-category suggestion configuration does not fall back to a parent. Prefer a single
  instance-wide configuration.
• Two request families, not one. Regular suggestions and item suggestions are
  separate requests. Merge them in the UI; don't expect a single combined payload like
  the legacy call returned.

FAQ

I used to make one autocomplete call. Why are there now two requests?
Tweakwise separates regular suggestions (search phrases, categories, filters) from
item suggestions (products, blogs, pages). Fire both while the user types and merge
them in your dropdown — this replaces the single legacy autocomplete response.

My category-specific suggestions stopped appearing after migrating. Why?
Suggestions do not inherit configuration. A suggestion aimed at a child category will
not fall back to a parent category's setup. Configure one instance-wide suggestion
configuration (or as few as possible) so every context is covered.

Do I still need my own debounce and request-cancellation logic?
For the API approach, yes — debounce input, cancel in-flight requests, and render only
the latest response, exactly as before. If you migrate to the Tweakwise JS function
method, the component handles the suggestion requests for you, so you mainly style the
result groups.